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.
- 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.
- 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.
- Returns a string indicating device state. Possible states are: "conn" - connected, "disc" - disconnected, "scan" scanning and "tryconn" - connecting.
- 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
On Python 3.x, this returns a dictionary view object, not a list.
- 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.
- 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.
- (deprecated since 0.9.10) Same as withDelegate().
- 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
If withResponse is true, will await confirmation that the write was successful from the device.
- 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.
- Device MAC address (as a hex string separated by colons).
- Device address type - one of ADDR_TYPE_PUBLIC or ADDR_TYPE_RANDOM; this will be a printable string.
- Bluetooth interface number (0 = /dev/hci0) used for the connection.
- 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.
- 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.
- Clears the current set of discovered devices.
- 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() ).
- Disables reception of advertising broadcasts. Should be called after process() has returned.
- Returns a list (a view on Python 3.x) of ScanEntry objects for all devices which have been discovered (since the last clear() call).
# 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.
- 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.
- 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.
- 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.
- Device MAC address (as a hex string separated by colons).
- Device address type - one of ADDR_TYPE_PUBLIC or ADDR_TYPE_RANDOM.
- Bluetooth interface number (0 = /dev/hci0) on which advertising information was seen.
- 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.
- Boolean value - True if the device supports connections, and False otherwise (typically used for advertising 'beacons').
- 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).
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.
- 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.
- 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()
- 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.
- The UUID expressed in binary (a str object on Python 2.x, bytes on 3.x).
More information about standard services can be found at https://www.bluetooth.org/en-us/specification/adopted-specifications
- 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.
- The Bluetooth UUID for this service.
- The Peripheral object for the device to which the service belongs.
- 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.
- Returns True if the characteristic can be read (as indicated by its properties) and False otherwise.
- Returns a string describing the characteristic properties ('READ', 'WRITE', etc).
- 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).
- The Bluetooth UUID for this characteristic.
- The Peripheral object for the device to which the characteristic belongs.
- A bitmask of properties for the characteristic.
- 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.
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 ) # 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 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
|November 12, 2020||0.9|