guangminglion/bleep

Python BLE Library for Linux and OS X

bleep

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

Installation

Linux

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 https://github.com/matthewelse/pygattlib.git
cd pygattlib
sudo python setup.py 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 setup.py 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:

brew install boost-python

git clone https://github.com/matthewelse/bleep.git
cd bleep
sudo python setup.py install

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

sudo python setup.py develop

Examples

tree.py

You can run tree.py 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: tree.py [-h] mac

Usage

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:

>>> device.services
[Generic Access, Generic Attribute, Device Information, Battery Service, Human Interface Device]

each service's characteristics

>>> service = device.services[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
Report
>>> 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)