Bluetooth Low Energy (BLE) Library for Python

pip install bleep==0.4.3



A BLE abstraction layer for Python inspired by bleat. Currently only supports Linux, with experimental support for Mac OS X.

Current Support

  • Discovering devices
  • Reading advertising data
  • Connecting to devices
  • Discovering services, characteristics and descriptors
  • Read from characteristics



First, install my fork of pygattlib and its dependencies:

sudo apt-get install libboost-python-dev libboost-thread-dev libbluetooth-dev libglib2.0-dev python-dev

You should also make sure that your version of libbluetooth is at least 4.101:

apt-cache policy libbluetooth-dev | grep Installed

Then, clone the repository, and install the python package.

git clone
cd pygattlib
sudo python install

This will build the dynamic library, and install the python package.

You can then install bleep easily:

sudo pip install bleep

If you want to develop bleep, instead of the last line, run:

sudo python develop

This will cause any changes you make to bleep to be reflected when you import the library.

NOTE: You may need to run all BLE code with sudo, even when using the Python interactive shell.

Mac OS X

Installation on Mac OS X is very simple:

git clone
cd bleep
sudo python install

Likewise, if you would like to develop bleep, run this instead of the last line:

sudo python develop


You can run to see all of the services, characteristics and descriptors attached to a device with a specific mac address. In order to find the device's mac address, you could use hcitool lescan, or use BLEDevice.discoverDevices().

usage: [-h] mac


Include bleep

>>> from bleep import BLEDevice

Scan for devices

>>> devices = BLEDevice.discoverDevices()
>>> devices
[Device Name:  (5A:79:8E:91:83:1C), Device Name:  (C1:20:68:1B:00:26), Device Name: BLE Keyboard (C9:E8:56:3B:4D:B1), Device Name:  (4C:25:F5:C2:E6:61), Device Name:  (60:03:08:B2:47:F1), Device Name:  (C1:62:3A:1D:00:14)]

This will return a list of Device objects, however you won't be connected to any of them, so pick one you like, and connect to it:

>>> device = devices[2]
>>> device.connect()

You can then access the device's services:

[Generic Access, Generic Attribute, Device Information, Battery Service, Human Interface Device]

each service's characteristics

>>> service =[4]
>>> service
Human Interface Device
>>> service.characteristics
[HID Information, Report Map, Protocol Mode, HID Control Point, Report, Report]

and each characteristic's descriptors

>>> char = service.characteristics[4]
>>> char
>>> char.descriptors
[Client Characteristic Configuration, Report Reference]

Useful Functionality

BLEDevice.discoverDevices supports parameters which allow you to specify which BLE device to connect to (ignored on OSes other than Linux), how long to sample for, as well as a function which returns a boolean value, allowing you to cherry-pick your devices.

def discoverDevices(device='hci0', timeout=5, filter=lambda x: True)