Bleak: Bluetooth Low Energy Client

Warnings

• breaking OS-specific GATT exceptions (e.g., `BleakDBusError`) are now wrapped in `BleakGATTProtocolError` for cross-platform consistency. If you were catching these specific exceptions, you should now catch `BleakGATTProtocolError` or both for multi-version compatibility.
  Fix: Catch `bleak.exc.BleakGATTProtocolError`. The `code` property of `BleakGATTProtocolError` can be used to get the actual underlying error code.
• deprecated The `adapter` keyword argument in `BleakScanner` and `BleakClient` has been deprecated. This affects how a specific Bluetooth adapter is selected.
  Fix: Use the new `bluez={'adapter': 'hci0'}` keyword argument instead. For compatibility, both can be passed, or the deprecation warning can be suppressed.
• breaking Support for Python 3.8 and macOS versions older than 10.13, and BlueZ versions older than 5.55 has been removed.
  Fix: Ensure your environment uses Python 3.10 or newer (as per PyPI `requires_python`), macOS 10.15 or newer, and BlueZ 5.55 or newer.
• gotcha Calling `asyncio.run()` multiple times in the same program can lead to crashes and incorrect behavior because Bleak requires all operations to use the same running asyncio event loop.
  Fix: Structure your code with a single asynchronous `main()` function that calls `asyncio.run(main())` only once at the program's entry point.
• gotcha Naming your Python script `bleak.py` will cause an `ImportError` due to a circular import, as Python will try to import your script instead of the installed library.
  Fix: Rename your script to something else (e.g., `my_ble_app.py`, `scanner.py`).
• gotcha The default connection timeout for `BleakClient` has been increased from 10 seconds to 30 seconds. This might affect applications expecting a quicker timeout.
  Fix: Adjust your connection logic if you rely on a shorter timeout, or explicitly set the `timeout` parameter in the `BleakClient` constructor or `connect()` method.
• deprecated Importing `bleak.args.*` types from `bleak.backends.*` has been deprecated.
  Fix: Adjust imports to use the correct `bleak.args` module directly for type hinting and argument handling.

Install

• pip install bleak Install stable release

Imports

• BleakScanner

  from bleak import BleakScanner

• BleakClient

  from bleak import BleakClient

• BleakError

  from bleak.exc import BleakError

• BleakGATTProtocolError

  from bleak.exc import BleakGATTProtocolError

• BleakDBusError

  from bleak.exc import BleakDBusError

  Pre-v3.0.0 specific GATT errors on BlueZ backend; now wrapped by BleakGATTProtocolError.

Quickstart

This quickstart demonstrates how to scan for nearby Bluetooth Low Energy devices using `BleakScanner` and then connect to a specific device using `BleakClient` to read a GATT characteristic, such as the battery level. It highlights the asynchronous nature of Bleak operations, requiring `asyncio` to run. Remember to replace placeholder UUIDs and addresses with those relevant to your device.

import asyncio
from bleak import BleakScanner, BleakClient

# Replace with the actual address of your BLE device
# For macOS, this might be a UUID. For Linux/Windows, a MAC address.
# You can find the address by running the discovery part first.
DEVICE_ADDRESS = "XX:XX:XX:XX:XX:XX" # Example for a generic device
SERVICE_UUID = "0000180f-0000-1000-8000-00805f9b34fb" # Battery Service UUID
BATTERY_LEVEL_CHAR_UUID = "00002a19-0000-1000-8000-00805f9b34fb" # Battery Level Characteristic UUID

async def discover_devices():
    print("Scanning for 5 seconds...")
    devices = await BleakScanner.discover(timeout=5.0)
    for d in devices:
        print(f"Device: {d.name} ({d.address})")
    print("\nDiscovery complete.")
    return devices

async def connect_and_read(address: str):
    try:
        async with BleakClient(address) as client:
            if not client.is_connected:
                print(f"Failed to connect to {address}")
                return
            print(f"Connected to {client.address}")

            # Read a characteristic (e.g., Battery Level)
            try:
                battery_level = await client.read_gatt_char(BATTERY_LEVEL_CHAR_UUID)
                print(f"Battery Level: {int.from_bytes(battery_level, 'little')}%")
            except Exception as e:
                print(f"Could not read battery level characteristic: {e}")
            
            # List all services and characteristics (optional)
            print("\nServices and Characteristics:")
            for service in client.services:
                print(f"  Service: {service.uuid} ({service.description})")
                for char in service.characteristics:
                    print(f"    Characteristic: {char.uuid} ({char.description}) - Properties: {char.properties}")
                    for descriptor in char.descriptors:
                        print(f"      Descriptor: {descriptor.uuid}")

    except Exception as e:
        print(f"An error occurred: {e}")

async def main():
    # First, discover devices to find the address
    # devices = await discover_devices()
    # For direct connection, replace DEVICE_ADDRESS with your target's address
    
    await connect_and_read(DEVICE_ADDRESS)

if __name__ == "__main__":
    # Make sure not to name your script 'bleak.py' to avoid circular import errors.
    asyncio.run(main())