BLUEPY(1) bluepy BLUEPY(1)

bluepy - bluepy Documentation

bluepy is a Python module which allows communication with Bluetooth Low Energy devices. The current implementation runs on Linux (internally it uses code from the BlueZ project), although it can be ported to other platforms.

To browse the API documentation, it is recommended to start with peripheral.

Contents:

Bluepy's Peripheral class encapsulates a connection to a Bluetooth LE peripheral. You create a Peripheral object directly by specifying its MAC address; when the connection is established, the services and characteristics offered by that device can be discovered and read or written.

Peripheral([deviceAddr=None[, addrType=ADDR_TYPE_PUBLIC[, iface=None]]])
If deviceAddr is not None, creates a Peripheral object and makes a connection to the device indicated by deviceAddr. deviceAddr should be a string comprising six hex bytes separated by colons, e.g. "11:22:33:ab:cd:ed".

If deviceAddr is None, creates an un-connected Peripheral object. You must call the connect() method on this object (passing it a device address) before it will be usable.

The addrType parameter can be used to select between fixed (btle.ADDR_TYPE_PUBLIC) and random (btle.ADDR_TYPE_RANDOM) address types, depending on what the target peripheral requires. See section 10.8 of the Bluetooth 4.0 specification for more details.

The iface parameter allows the Bluetooth interface on which to make the connection to be set. On Linux, 0 means /dev/hci0, 1 means /dev/hci1 and so on.

deviceAddr may also be a ScanEntry object. In this case the device address, address type, and interface number are all taken from the ScanEntry values, and the addrType and iface parameters are ignored.

The constructor will throw a BTLEException if connection to the device fails.

connect(addr[, addrType=ADDR_TYPE_PUBLIC[, iface=None]])
Makes a connection to the device indicated by addr, with address type addrType and interface number iface (see the Peripheral constructor for details). You should only call this method if the Peripheral is un-connected (i.e. you did not pass a addr to the constructor); a given peripheral object cannot be re-connected once connected.
disconnect()
Drops the connection to the device, and cleans up associated OS resources. Although the Python destructor for a Peripheral will attempt to call this method, you should not rely on this happening at any particular time. Therefore, always explicitly call disconnect() if you have finished communicating with a device.
getState()
Returns a string indicating device state. Possible states are: "conn" - connected, "disc" - disconnected, "scan" scanning and "tryconn" - connecting.
getServices()
Returns a list of Service objects representing the services offered by the peripheral. This will perform Bluetooth service discovery if this has not already been done; otherwise it will return a cached list of services immediately.

On Python 3.x, this returns a dictionary view object, not a list.

getServiceByUUID(uuidVal)
Returns an instance of a Service object which has the indicated UUID. uuidVal can be a UUID object, or any string or integer which can be used to construct a UUID object. The method will return immediately if the service was previously discovered (e.g. by getServices()), and will query the peripheral otherwise. It raises a BTLEEException if the service is not found.
getCharacteristics(startHnd=1, endHnd=65535, uuid=None)
Returns a list containing Characteristic objects for the peripheral. If no arguments are given, will return all characteristics. If startHnd and/or endHnd are given, the list is restricted to characteristics whose handles are within the given range - note that it's usually more convenient to use Service.getCharacteristics() to get the characteristics associated with a particular service. Alternatively, uuid may be specified to locate a characteristic with a particular UUID value. uuid may be any string, integer, or UUID type which can be used to construct a UUID object.

If no matching characteristics are found, returns an empty list.

getDescriptors(startHnd=1, endHnd=65535)
Returns a list containing Descriptor objects for the peripheral. If no arguments are given, will return all descriptors. If startHnd and/or endHnd are given, the list is restricted to descriptors whose handles are within the given range. Again, it's usually more convenient to use Service.getDescriptors() to get the descriptors associated with a particular service.

If no matching descriptors are found, returns an empty list.

withDelegate(delegate)
This stores a reference to a "delegate" object, which is called when asynchronous events such as Bluetooth notifications occur. This should be a subclass of the DefaultDelegate class. See notifications for more information. This method returns the Peripheral object.
setDelegate(delegate)
(deprecated since 0.9.10) Same as withDelegate().
waitForNotifications(timeout)
Blocks until a notification is received from the peripheral, or until the given timeout (in seconds) has elapsed. If a notification is received, the delegate object's handleNotification() method will be called, and waitForNotifications() will then return True.

If nothing is received before the timeout elapses, this will return False.

writeCharacteristic(handle, val, withResponse=False)
Writes the data val (of type str on Python 2.x, byte on 3.x) to the characteristic identified by handle handle, which should be an integer in the range 1 to 65535. This is useful if you know a characteristic's GATT handle, but do not have a Characteristic object.

If withResponse is true, will await confirmation that the write was successful from the device.

readCharacteristic(handle)
Reads the current value of the characteristic identified by handle. This is useful if you know the handle for the characteristic but do not have a suitable Characteristic object.

All the properties listed below are read-only.
addr
Device MAC address (as a hex string separated by colons).
addrType
Device address type - one of ADDR_TYPE_PUBLIC or ADDR_TYPE_RANDOM; this will be a printable string.
iface
Bluetooth interface number (0 = /dev/hci0) used for the connection.

A Scanner object is used to scan for LE devices which are broadcasting advertising data. In most situations this will give a set of devices which are available for connection. (Note, however, that Bluetooth LE devices may accept connections without broadcasting advertising data, or may broadcast advertising data but may not accept connections).

Scanner([index=0])
Creates and initialises a new scanner object. index identifies the Bluetooth interface to use (where 0 is /dev/hci0 etc). Scanning does not start until the start() or scan() methods are called - see below for details.

withDelegate(delegate)
Stores a reference to a delegate object, which receives callbacks when broadcasts from devices are received. See the documentation for DefaultDelegate for details.
scan([timeout = 10])
Scans for devices for the given timeout in seconds. During this period, callbacks to the delegate object will be called. When the timeout ends, scanning will stop and the method will return a list (or a view on Python 3.x) of ScanEntry objects for all devices discovered during that time.

scan() is equivalent to calling the clear(), start(), process() and stop() methods in order.

clear()
Clears the current set of discovered devices.
start()
Enables reception of advertising broadcasts from peripherals. Should be called before calling process().
process([timeout = 10])
Waits for advertising broadcasts and calls the delegate object when they are received. Returns after the given timeout period in seconds. This may be called multiple times (between calls to start() and stop() ).
stop()
Disables reception of advertising broadcasts. Should be called after process() has returned.
getDevices()
Returns a list (a view on Python 3.x) of ScanEntry objects for all devices which have been discovered (since the last clear() call).

Basic code to run a LE device scan for 10 seconds follows this example:
# import the necessary parts of the bluepy library
from bluepy.btle import Scanner, DefaultDelegate
# create a delegate class to receive the BLE broadcast packets
class ScanDelegate(DefaultDelegate):
    def __init__(self):
        DefaultDelegate.__init__(self)
    # when this python script discovers a BLE broadcast packet, print a message with the device's MAC address
    def handleDiscovery(self, dev, isNewDev, isNewData):
        if isNewDev:
            print "Discovered device", dev.addr
        elif isNewData:
            print "Received new data from", dev.addr
# create a scanner object that sends BLE broadcast packets to the ScanDelegate
scanner = Scanner().withDelegate(ScanDelegate())
# create a list of unique devices that the scanner discovered during a 10-second scan
devices = scanner.scan(10.0)
# for each device  in the list of devices
for dev in devices:
    # print  the device's MAC address, its address type,
    # and Received Signal Strength Indication that shows how strong the signal was when the script received the broadcast.
    print "Device %s (%s), RSSI=%d dB" % (dev.addr, dev.addrType, dev.rssi)
    # For each of the device's advertising data items, print a description of the data type and value of the data itself
    # getScanData returns a list of tupples: adtype, desc, value
    # where AD Type means “advertising data type,” as defined by Bluetooth convention:
    # https://www.bluetooth.com/specifications/assigned-numbers/generic-access-profile
    # desc is a human-readable description of the data type and value is the data itself
    for (adtype, desc, value) in dev.getScanData():
        print "  %s = %s" % (desc, value)

For continuous scanning, follow this example:

# import the necessary parts of the bluepy library
from bluepy.btle import Scanner, DefaultDelegate
# create a delegate class to receive the BLE broadcast packets
class ScanDelegate(DefaultDelegate):
    def __init__(self):
        DefaultDelegate.__init__(self)
    # when this python script discovers a BLE broadcast packet, print a message with the device's MAC address
    def handleDiscovery(self, dev, isNewDev, isNewData):
        if isNewDev:
            print "Discovered device", dev.addr
        elif isNewData:
            print "Received new data from", dev.addr
# create a scanner object that sends BLE broadcast packets to the ScanDelegate
scanner = Scanner().withDelegate(ScanDelegate())
# start the scanner and keep the process running
scanner.start()
while True:
    print "Still running..."
    scanner.process()

NOTE that (1) LE scanning must be run as root and (2) the continuous scanning code never completes, so you'll need to do useful things in the handleDiscovery() method of your delegate.

See the documentation for ScanEntry for the information available via the dev parameter passed to the delegate.

A ScanEntry object contains information received from a Bluetooth LE device received during Scanner operation. This includes parameters needed to connect to the device (MAC address, address type), and advertising data (such as its name or available services) supplied in the device's broadcasts.

ScanEntry objects are created by the Scanner class, and should not be created by the user.

getDescription(adtype)
Returns a human-readable description of the advertising data 'type' code adtype. For instance, an adtype value of 9 would return the string "Complete Local Name". See the Generic Access Profile assigned numbers at https://www.bluetooth.org/en-us/specification/assigned-numbers/generic-access-profile for a complete list.
getValueText(adtype)
Returns a human-readable string representation of the advertising data for code adtype. Values such as the 'local name' are returned as strings directly; other values are converted to hex strings. If the requested data is not available, None is returned.
getScanData()
Returns a list of tuples (adtype, description, value) containing the AD type code, human-readable description and value (as reported by getDescription() and getValueText()) for all available advertising data items.

All the properties listed below are read-only.
addr
Device MAC address (as a hex string separated by colons).
addrType
Device address type - one of ADDR_TYPE_PUBLIC or ADDR_TYPE_RANDOM.
iface
Bluetooth interface number (0 = /dev/hci0) on which advertising information was seen.
rssi
Received Signal Strength Indication for the last received broadcast from the device. This is an integer value measured in dB, where 0 dB is the maximum (theoretical) signal strength, and more negative numbers indicate a weaker signal.
connectable
Boolean value - True if the device supports connections, and False otherwise (typically used for advertising 'beacons').
updateCount
Integer count of the number of advertising packets received from the device so far (since clear() was called on the Scanner object which found it).

bluepy functions which receive Bluetooth messages asynchronously - such as notifications, indications, and advertising data - pass this information to the user by calling methods on a 'delegate' object.

To be useful, the delegate object will be from a class created by the user. Bluepy's DefaultDelegate is a base class for this - you should override some or all of the methods here with your own application-specific code.

DefaultDelegate()
Initialises the object instance.

handleNotification(cHandle, data)
Called when a notification or indication is received from a connected Peripheral object. cHandle is the (integer) handle for the characteristic - this can be used to distinguish between notifications from multiple sources on the same peripheral. data is the characteristic data (a str type on Python 2.x, and bytes on 3.x).
handleDiscovery(scanEntry, isNewDev, isNewData)
Called when advertising data is received from an LE device while a Scanner object is active. scanEntry contains device information and advertising data - see the ScanEntry class for details. isNewDev is True if the device (as identified by its MAC address) has not been seen before by the scanner, and False otherwise. isNewData is True if new or updated advertising data is available.

UUID(value)
Constructs a UUID object with the given value. This may be:
  • an int value in the range 0 to 0xFFFFFFFF
  • a str value
  • another UUID object
  • any other value which can be converted to hex digits using str()

getCommonName()
Returns string describing that UUID. If the UUID is one listed in assignednumbers this will be a human-readable name e.g. "Cycling Speed and Cadence". Otherwise, it will be a hexadecimal string.

All the properties listed below are read-only.
binVal
The UUID expressed in binary (a str object on Python 2.x, bytes on 3.x).

A Bluetooth LE Service object represents a collection of characteristics and descriptors which are all related to one particular function of the peripheral. This allows particular characteristics to be discovered without having to enumerate everything offered by that peripheral.

More information about standard services can be found at https://www.bluetooth.org/en-us/specification/adopted-specifications

You should not construct Service objects directly. Instead, use the getServices() or getServiceByUUID() methods of a connected Peripheral object.

getCharacteristics([forUUID=None])
Returns a list of Characteristic objects associated with the service. If this has not been done before, the peripheral is queried. Otherwise, a cached list if returned. If forUUID is given, it may be a UUID object or a value used to construct one. In this case the returned list, which may be empty, contains any characteristics associated with the service which match that UUID.

All the properties listed below are read-only.
uuid
The Bluetooth UUID for this service.
peripheral
The Peripheral object for the device to which the service belongs.

A Bluetooth LE "characteristic" represents a short data item which can be read or written. These can be fixed (e.g. a string representing the manufacturer name) or change dynamically (such as the current temperature or state of a button). Most interaction with Bluetooth LE peripherals is done by reading or writing characteristics.

You should not construct Characteristic objects directly. Instead, use the getCharacteristics() method of a connected Peripheral object.

read()
Reads the current value of a characteristic as a string of bytes. For Python 2.x this is a value of type str, and on Python 3.x this is of type bytes. This may be used with the struct module to extract integer values from the data.
write(data[, withResponse=False])
Writes the given data to the characteristic. data should be of type str for Python 2.x, and type bytes for Python 3.x. Bluetooth LE allows the sender to request the peripheral to send a response to confirm that the data has been received. Setting the withResponse parameter to True will make this request. A BTLEException will be raised if the confirmation process fails.
supportsRead()
Returns True if the characteristic can be read (as indicated by its properties) and False otherwise.
propertiesToString()
Returns a string describing the characteristic properties ('READ', 'WRITE', etc).
getHandle()
Returns the 16-bit integer value used to identify the characteristic in the underlying GATT protocol. This may be useful to distinguish between notifications from different characteristics (see notifications for further information).

All the properties listed below are read-only.
uuid
The Bluetooth UUID for this characteristic.
peripheral
The Peripheral object for the device to which the characteristic belongs.
properties
A bitmask of properties for the characteristic.

The Descriptor class is a placeholder. bluepy does not currently support any useful operations with descriptors.

In bluepy, notifications are processed by creating a "delegate" object and registering it with the Peripheral. A method in the delegate is called whenever a notification is received from the peripheral, as shown below:
handleNotification(cHandle, data)
Called when a notification has been received from a Peripheral. Normally you will call the peripheral's waitForNotifications() method to allow this, but note that a Bluetooth LE device may transmit notifications at any time. This means that handleNotification() can potentially be called when any BluePy call is in progress.

The cHandle parameter is the GATT 'handle' for the characteristic which is sending the notification. If a peripheral sends notifications for more than one characteristic, this may be used to distinguish them. The 'handle' value can be found by calling the getHandle() method of a Characteristic object.

The data parameter is a str (Python 2.x) or bytes (Python 3.x) value containing the notification data. It is recommended you use Python's struct module to unpack this, to allow portability between language versions.

It is recommended that the class used for the delegate object is derived from btle.DefaultDelegate. This will ensure that an appropriate default method exists for any future calls which may be added to the delegate interface.

Code to receive notifications from a peripheral can follow the outline below:
import btle
class MyDelegate(btle.DefaultDelegate):
    def __init__(self, params):
        btle.DefaultDelegate.__init__(self)
        # ... initialise here
    def handleNotification(self, cHandle, data):
        # ... perhaps check cHandle
        # ... process 'data'
# Initialisation  -------
p = btle.Peripheral( address )
p.setDelegate( MyDelegate(params) )
# Setup to turn notifications on, e.g.
#   svc = p.getServiceByUUID( service_uuid )
#   ch = svc.getCharacteristics( char_uuid )[0]
#   ch.write( setup_data )
# Main loop --------
while True:
    if p.waitForNotifications(1.0):
        # handleNotification() was called
        continue
    print "Waiting..."
    # Perhaps do something else here

The AssignedNumbers object is a convenient way to refer to common Bluetooth-related Assigned Numbers by using textual names. So, for instance AssignedNumbers.firmwareRevisionString is a UUID object for the Firmware Revision String characteristic identifier (0x2A26).

The complete list of Bluetooth assigned numbers is given at https://www.bluetooth.org/en-us/specification/assigned-numbers

The current version of bluepy includes the following defined values:

alertNotificationService
batteryLevel
batteryService
bloodPressure
currentTimeService
cyclingPower
cyclingSpeedAndCadence
deviceInformation
deviceName
firmwareRevisionString
genericAccess
genericAttribute
glucose
hardwareRevisionString
healthThermometer
heartRate
humanInterfaceDevice
immediateAlert
linkLoss
locationAndNavigation
manufacturerNameString
modelNumberString
nextDstChangeService
phoneAlertStatusService
referenceTimeUpdateService
runningSpeedAndCadence
scanParameters
serialNumberString
softwareRevisionString
txPower
txPowerLevel
userData
  • genindex
  • modindex
  • search

Ian Harvey

2020, Ian Harvey
November 12, 2020 0.9