Bluepy: Python interface to Bluetooth LE on Linux

From UNamur InfoSec
Jump to navigation Jump to search

Installation

Follow the instruction on official page on: https://github.com/IanHarvey/bluepy or the do the following: To install the current released version, on most Debian-based systems:

sudo apt-get install python-pip libglib2.0-dev
sudo pip install bluepy

After installation, we can import the library into our python project:

import btle

Scan for deivces

The official document for Scanner class can be found at: http://ianharvey.github.io/bluepy-doc/scanner.html The library come with a class called “Scanner” that allow us to scan for LE devices. We will import the class with “from btle import Scanner” for example to scan and print all discovered devices.

from bluepy.btle import Scanner
scanner = Scanner()
devices = scanner.scan(10.0)

for dev in devices:
    print "Device %s (%s), RSSI=%d dB" % (dev.addr, dev.addrType, dev.rssi)
    for (adtype, desc, value) in dev.getScanData():
        print "  %s = %s" % (desc, value)

We can also set a custom scan delegate to handler the device discovery, for example a scan delegate function that print the address of discovered devices.

from bluepy.btle import Scanner, DefaultDelegate
import time

class ScanDelegate(DefaultDelegate):
    def __init__(self):
        DefaultDelegate.__init__(self)

    def handleDiscovery(self, dev, isNewDev, isNewData):
        if isNewDev:
            print "Discovered device", dev.addr
        elif isNewData:
            print "Received new data from", dev.addr

scanner = Scanner().withDelegate(ScanDelegate())
devices = scanner.scan(10.0)

while True:
    time.sleep(1)


Connect to device

The official document for “Peripheral” class is available at: http://ianharvey.github.io/bluepy-doc/peripheral.html We can use the Peripheral class of the library to connect to the device, in order to read from/write to device’s service’s characteristic. For example to read a heart-rate measurement (UUID= 0x2A37) from device with address “11:22:33:44:55:66”.

from bluepy.btle import Peripheral

p = Peripheral(’11:22:33:44:55:66’, ‘random’)
c = p. getCharacteristics(uuid=’00002A3700001000800000805F9B34FB’)[0]
print c.read()

Note: To construct the UUID from 16-bit or 32-bit short value. We simply add the short value to the base UUID: xxxxxxxx-0000-1000-8000-00805F9B34FB. Replace the xxxxxx with short UUID. We can also write the characteristic of the device with the “write” function. Simply replace read with “write(value)”. The available functions for Characteristic class are here in the official document: http://ianharvey.github.io/bluepy-doc/characteristic.html


Using Nordic’s UART service to send and receive data

The Nordic’s UART service is the service implement in Bluetooth low energy device to allow two ways communication to the device. The service has two characteristics, one for writing (sending data to device) and the other one for reading (receiving data from device).

The base UUID of the service is: 6E400002-B5A3-F393-­E0A9-­E50E24DCCA9E. And the write UUID: 0x0002 (or 6E400001-B5A3-F393-­E0A9-­E50E24DCCA9E). Read UUID: 0x0003 (or 6E400003-B5A3-F393-­E0A9-­E50E24DCCA9E.

Note: we construct the UUID id by replacing the short value in base UUID.

Online document about the service is available at: https://learn.adafruit.com/introducing-adafruit-ble-bluetooth-low-energy-friend/uart-service Like any other service in Bluetooth low energy devices. We can use bluepy library on Raspberry Pi 3 to connect to the device. And read from RX: 0x0003 for receiving data. And write to TX: 0x0002 for sending data.

Note: the Bluetooth low energy device need to also implement the Nordic’s UART service with the same UUID too, in order to support the two ways communication.

The example code for Adafruit_BluefruitLE_nRF51 (Arduino device) is available at: https://github.com/adafruit/Adafruit_BluefruitLE_nRF51/tree/master/examples/bleuart_datamode

Additional documents

UART Service (Adafruit website): https://learn.adafruit.com/introducing-adafruit-ble-bluetooth-low-energy-friend/uart-service

Bluepy class reference: http://ianharvey.github.io/bluepy-doc/index.html

Bluepy Github link: https://github.com/IanHarvey/bluepy

Gatt Characteristic UUID: https://www.bluetooth.com/specifications/gatt/characteristics

Base UUID (BLE Specification): https://www.bluetooth.com/specifications/assigned-numbers/service-discovery