BLUEPY(1)

📦 version 1.3.0, in arch rolling

💖 BLUEPY(1) — bluepy 💖

🌸 NAME 🌸

Okay bestie, welcome to the BLUEPY(1) manual — this whole thing is literally about bluepy, no cap.

bluepy is a Python module that lets you communicate with Bluetooth Low Energy devices. The current implementation runs on Linux — internally it uses code from the BlueZ project at http://www.bluez.org/ — 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, this 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, it 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 an 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. 💀

Fr fr, the destructor is not your bestie here — call disconnect() yourself.

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 💖

Okay so a Scanner object is your little LE-device detective 🕵️‍♀️ — it scans for LE devices that are broadcasting advertising data. In most situations this gives you a set of devices that are available for connection. But bestie, plot twist: Bluetooth LE devices may accept connections without broadcasting advertising data, or they may broadcast advertising data but may not accept connections. So don't @ me when the vibes don't match the list. 💅

✨ 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 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. It's giving "receipts from the BLE world." 🧚

🌸 Constructor 🌸

ScanEntry objects are created by the Scanner class, and should not be created by the user. No DIY-ing this one, bestie.

💜 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 <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.

🎀 Properties 🎀

All the properties listed below are read-only. Read-only means look, don't touch. 👑

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. It's literally the bat-signal but for BLE events. 🦋

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. Customize bestie, don't just leave it bland.

✨ 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:
- 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()

💜 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 💖

Okay so a Bluetooth LE Service object is basically a little squad of characteristics and descriptors that all belong to one particular function of the peripheral. The point? You can discover just the characteristics you care about instead of enumerating literally everything the peripheral offers. Slay.

More info about standard services lives at https://www.bluetooth.org/en-us/specification/adopted-specifications 🦋

🎀 Constructor

Do not construct Service objects directly, bestie. Use the getServices() or getServiceByUUID() methods of a connected Peripheral object instead. That's the vibe.

✨ Instance Methods

getCharacteristics([forUUID=None]) — returns a list of Characteristic objects associated with the service. If this hasn't been done before, the peripheral gets queried. Otherwise, you get the cached list back. If forUUID is given, it may be a UUID object or a value used to construct one. In that case the returned list — which may be empty — contains any characteristics associated with the service that match that UUID.

🌸 Properties

All the properties listed below are read-only. No cap.

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" is a short data item that can be read or written. These can be fixed (e.g. a string representing the manufacturer name) or change dynamically (like the current temperature or state of a button). Most interaction with Bluetooth LE peripherals is done by reading or writing characteristics. It's giving main character energy, fr fr.

🎀 Constructor

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

✨ 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. Periodt.

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. That's it. That's the whole section. 😭

🌈 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 handleNotification() can potentially be called when any BluePy call is in progress. Keep that in mind, bestie.

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. Very demure, very portable. 💅

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). Iconic.

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

Tiny doc-nav bits on the page: Index, Module Index, Search Page.

👑 Author

Ian Harvey

© Copyright

2014, Ian Harvey

💖 And that's the whole BLUEPY(1) page, bestie! Source/version: 0.9, dated Dec 14, 2025. You ate that. Periodt. 💅✨

📦 where this page comes from

arch rolling: python-bluepy 1.3.0-12 · GPL2
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash-1017 on 2026-11-04: a language model's rewrite of the original, under its terms

BLUEPY(1)

💖 BLUEPY(1) — bluepy 💖

🌸 NAME 🌸

👑 THE PERIPHERAL CLASS 👑

🛠️ Constructor 🛠️

💫 Instance Methods 💫

🎀 Properties 🎀

💖 THE SCANNER CLASS 💖

✨ Constructor ✨

💅 Instance Methods 💅

🌈 Sample code 🌈

🦋 THE SCANENTRY CLASS 🦋

🌸 Constructor 🌸

💜 Instance Methods 💜

🎀 Properties 🎀

🎀 THE DEFAULTDELEGATE CLASS 🎀

✨ Constructor ✨

💅 Instance Methods 💅

👑 THE UUID CLASS 👑

🌟 Constructor 🌟

💜 Instance Methods 💜

🎀 Properties 🎀

💖 THE SERVICE CLASS 💖

🎀 Constructor

✨ Instance Methods

🌸 Properties

👑 THE CHARACTERISTIC CLASS 👑

🎀 Constructor

✨ Instance Methods

🌸 Properties

💀 THE DESCRIPTOR CLASS 💀

🌈 WORKING WITH NOTIFICATIONS 🌈

💬 handleNotification(cHandle, data)

🧚 Example code

🌟 ASSIGNED NUMBERS 🌟

👑 Author

© Copyright

💬 `handleNotification(cHandle, data)`