This Module allows reading and writing to GATT descriptors on devices such as fitness trackers, sensors, and anything implementing standard GATT Descriptor behavior.
pygatt provides a Pythonic API by wrapping two different backends:
- BlueZ's
gatttoolcommand-line utility. - Bluegiga's BGAPI, compatble with dongles like the BLED112.
Requires Python 2.7.
Despite the popularilty of BLE, we have yet to find a good programming interface
for it on desktop computers. Since most peripherals are designed to work with
smartphones, this space is neglected. One interactive interface, BlueZ's
gatttool, is functional but difficult to use programatically. BlueZ itself
obviously works, but the interface leaves something to be desired only
works in Linux.
pygatt consists of a front end that provies an API and two interchangable backends that implement the Bluetooth communication using differently. The backend can either use gatttool/BlueZ or a Bluegiga BGAPI compatible inteface. gatttool/BlueZ is Linux only whereas the BGAPI is cross platform.
The front end class pygatt.pygatt.BLEDevice represents a remote BLE device. The API provides the methods -- connect, char_read, char_write, subscribe -- that you need to interact with the device. When a BluetoothLEDevice object is created, there is an optional argument "backend" that allows for selection of the backend used. The default is gattool but the BGAPI can be used by setting the optional bled112 arguement to an instance of a BGAPIBackend. Note that there are optional arguments for some of the methods of BluetoothLEDevice that must be specified when using one backend and not the other.
This backend uses a minimalist implementation of Bluegiga's BGAPI to execute the Bluetooth communication. In this case, the class used by BluetoothLEDevice is pygatt.backends.BGAPIBackend.
BGAPIBackend in turn uses pygatt.backends.bgapi.bglib to communicate with the BLED112 dongle. BGLib's job is to construct comands for the dongle and parse the bytes received from the dongle into packets. BGAPIBackend's job is to manage the timing of commands, handling of the data, and keep track of the state of the dongle and connection to the remote device.
- The BGAPI backend should work on Linux, Windows, and Mac OS and has no other external dependencies.
This backend uses gatttool/BlueZ on Linux to execute the Bluetooth communication. In this case, the class used by BluetoothLEDevice is pygatt.gatttool_classes.GATTToolBackend. GATTToolBackend uses the python module pexpect to execute gatttool commannds as if a user were entering them on the comand line.
- Currently the gatttool backend is currently only tested under Linux as it
requires
gatttoolwhich is included with BlueZ which is a Linux library. - BlueZ >= 5.5
- Tested on 5.18 and 5.21
- Ubuntu is stuck on BlueZ 4.x and does not work - you need to build BlueZ from source.
Install pygatt with pip:
$ pip install https://github.com/stratosinc/pygatt
The BlueZ backend is not supported by default as it requires pexpect, which
can only be installed in a UNIX-based environment. If you wish to use that
backend, install the optional dependencies with:
$ pip install pygatt[GATTTOOL]
- Jeff Rowberg @jrowberg https://github.com/jrowberg/bglib
- Greg Albrecht @ampledata https://github.com/ampledata/pygatt
- Christopher Peplin @peplin https://github.com/stratosinc/pygatt
- Morten Kjaergaard @mkjaergaard https://github.com/mkjaergaard/pygatt
- Michael Saunby @msaunby https://github.com/msaunby/ble-sensor-pi
- Steven Sloboda [email protected] https://github.com/sloboste
Derived from the work of several others, see NOTICE.
Copyright 2015 Stratos Inc. and Orion Labs
Apache License, Version 2.0 and MIT License. See LICENSE.