BLUEPY(1) bluepy BLUEPY(1)
NAME
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 The
Peripheral class <#peripheral>.
Contents:
THE PERIPHERAL CLASS
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.
Constructor
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.
Instance Methods
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=0xFFFF, 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=0xFFFF)
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
Working with notifications <#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.
Properties
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.
THE SCANNER CLASS
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).
Constructor
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.
Instance Methods
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).
Sample code
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.
THE SCANENTRY CLASS
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.
Constructor
ScanEntry objects are created by the Scanner class, and should not be
created by the user.
Instance Methods
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 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.
Properties
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).
THE DEFAULTDELEGATE CLASS
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.
Constructor
DefaultDelegate()
Initialises the object instance.
Instance Methods
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.
THE UUID CLASS
Constructor
UUID(value)
Constructs a UUID object with the given value. This may be:
o an int value in the range 0 to 0xFFFFFFFF
o a str value
o another UUID object
o any other value which can be converted to hex digits using
str()
Instance Methods
getCommonName()
Returns string describing that UUID. If the UUID is one listed
in Assigned Numbers <#assignednumbers> this will be a
human-readable name e.g. "Cycling Speed and Cadence".
Otherwise, it will be a hexadecimal string.
Properties
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).
THE SERVICE CLASS
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
Constructor
You should not construct Service objects directly. Instead, use the
getServices() or getServiceByUUID() methods of a connected Peripheral
object.
Instance Methods
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.
Properties
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.
THE CHARACTERISTIC CLASS
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.
Constructor
You should not construct Characteristic objects directly. Instead, use
the getCharacteristics() method of a connected Peripheral object.
Instance Methods
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 Working with notifications <#notifications>
for further information).
Properties
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
The Descriptor class is a placeholder. bluepy does not currently
support any useful operations with descriptors.
WORKING WITH NOTIFICATIONS
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.
Example code
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
ASSIGNED NUMBERS
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
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
o Index <>
o Module Index <>
o Search Page <>
Author
Ian Harvey
Copyright
2014, Ian Harvey
0.9 December 14, 2025 BLUEPY(1)