# API reference

Contents:

- BleakScanner class
  - `BleakScanner`
  - Easy methods
  - Starting and stopping
  - Getting discovered devices and advertisement data
  - Extra information
- BleakClient class
  - `BleakClient`
  - Connecting and disconnecting
  - Device information
  - GATT Client Operations
  - Pairing/bonding
- Args modules
  - BlueZ backend arguments
  - `BlueZClientArgs`
  - `BlueZDiscoveryFilters`
  - `BlueZNotifyArgs`
  - `BlueZScannerArgs`
  - `OrPattern`
  - CoreBluetooth backend arguments
  - `CBScannerArgs`
  - `CBStartNotifyArgs`
  - WinRT backend arguments
  - `WinRTClientArgs`

## Class representing BLE devices

Generated by `bleak.discover()` and `bleak.backends.scanning.BaseBleakScanner`.

Wrapper class for Bluetooth LE servers returned from calling `bleak.discover()`.

class bleak.backends.device.BLEDevice(address: str, name: str | None, details: Any, **kwargs: Any)

  A simple wrapper class representing a BLE server detected during scanning.

  address

    The Bluetooth address of the device on this machine (UUID on macOS).

  details

    The OS native details required for connecting to the device.

  name

    The operating system name of the device (not necessarily the local name from the advertising data), suitable for display to the user.

## GATT objects

Gatt Service Collection class and interface class for the Bleak representation of a GATT Service.

class bleak.backends.service.BleakGATTService(obj: Any, handle: int, uuid: str)

  The Bleak representation of a GATT Service.

  add_characteristic(characteristic: BleakGATTCharacteristic) → None

    Add a `BleakGATTCharacteristic` to the service.

    Should not be used by end user, but rather by bleak itself.

  property characteristics: list[BleakGATTCharacteristic]

    List of characteristics for this service

  property description: str

    String description for this service

  get_characteristic(uuid: str | UUID) → BleakGATTCharacteristic | None

    Get a characteristic by UUID.

    Parameters:

      uuid – The UUID to match.

    Returns:

      The first characteristic matching `uuid` or `None` if no matching characteristic was found.

  property handle: int

    The handle of this service

  property uuid: str

    The UUID to this service

class bleak.backends.service.BleakGATTServiceCollection

  Simple data container for storing the peripheral’s service complement.

  add_characteristic(characteristic: BleakGATTCharacteristic) → None

    Add a `BleakGATTCharacteristic` to the service collection.

    Should not be used by end user, but rather by bleak itself.

  add_descriptor(descriptor: BleakGATTDescriptor) → None

    Add a `BleakGATTDescriptor` to the service collection.

    Should not be used by end user, but rather by bleak itself.

  add_service(service: BleakGATTService) → None

    Add a `BleakGATTService` to the service collection.

    Should not be used by end user, but rather by bleak itself.

  property characteristics: dict[int, BleakGATTCharacteristic]

    Returns dictionary of handles mapping to BleakGATTCharacteristic

  property descriptors: dict[int, BleakGATTDescriptor]

    Returns a dictionary of integer handles mapping to BleakGATTDescriptor

  get_characteristic(specifier: int | str | UUID) → BleakGATTCharacteristic | None

    Get a characteristic by handle (int) or UUID (str or uuid.UUID)

  get_descriptor(handle: int) → BleakGATTDescriptor | None

    Get a descriptor by integer handle

  get_service(specifier: int | str | UUID) → BleakGATTService | None

    Get a service by handle (int) or UUID (str or uuid.UUID)

  property services: dict[int, BleakGATTService]

    Returns dictionary of handles mapping to BleakGATTService

Interface class for the Bleak representation of a GATT Characteristic

class bleak.backends.characteristic.BleakGATTCharacteristic(obj: Any, handle: int, uuid: str, properties: list[CharacteristicPropertyName], max_write_without_response_size: Callable[[], int], service: BleakGATTService)

  The Bleak representation of a GATT Characteristic

  add_descriptor(descriptor: BleakGATTDescriptor) → None

    Add a `BleakGATTDescriptor` to the characteristic.

    Should not be used by end user, but rather by bleak itself.

  property description: str

    Description for this characteristic

  property descriptors: list[BleakGATTDescriptor]

    List of descriptors for this service

  get_descriptor(specifier: int | str | UUID) → BleakGATTDescriptor | None

    Get a descriptor by handle (int) or UUID (str or uuid.UUID)

  property handle: int

    The handle for this characteristic

  property max_write_without_response_size: int

    Gets the maximum size in bytes that can be used for the data argument of `BleakClient.write_gatt_char()` when `response=False`.

    In rare cases, a device may take a long time to update this value, so reading this property may return the default value of `20` and reading it again after a some time may return the expected higher value.

    If you really need to wait for a higher value, you can do something like this:

        async with asyncio.timeout(10):
            while char.max_write_without_response_size == 20:
                await asyncio.sleep(0.5)

    Warning

    Linux quirk: For BlueZ versions < 5.62, this property will always return `20`.

    Added in version 0.16.

  property properties: list[Literal['broadcast', 'read', 'write-without-response', 'write', 'notify', 'indicate', 'authenticated-signed-writes', 'extended-properties', 'reliable-write', 'writable-auxiliaries', 'encrypt-read', 'encrypt-write', 'encrypt-authenticated-read', 'encrypt-authenticated-write', 'authorize']]

    Properties of this characteristic

  property service_handle: int

    The integer handle of the Service containing this characteristic

  property service_uuid: str

    The UUID of the Service containing this characteristic

  property uuid: str

    The UUID for this characteristic

class bleak.backends.characteristic.GattCharacteristicsFlags(*values)

Interface class for the Bleak representation of a GATT Descriptor

class bleak.backends.descriptor.BleakGATTDescriptor(obj: Any, handle: int, uuid: str, characteristic: BleakGATTCharacteristic)

  The Bleak representation of a GATT Descriptor

  property characteristic_handle: int

    handle for the characteristic that this descriptor belongs to

  property characteristic_uuid: str

    UUID for the characteristic that this descriptor belongs to

  property description: str

    A text description of what this descriptor represents

  property handle: int

    Integer handle for this descriptor

  property uuid: str

    UUID for this descriptor

## Exceptions

exception bleak.exc.BleakBluetoothNotAvailableError(msg: str, reason: BleakBluetoothNotAvailableReason)

  Exception which is raised if the Bluetooth access is not available for some reason.

  Added in version 2.0.

  property reason: BleakBluetoothNotAvailableReason

    Gets the reason why Bluetooth is not available.

class bleak.exc.BleakBluetoothNotAvailableReason(*values)

  Reasons for Bluetooth not being available.

  Added in version 2.0.

  DENIED_BY_SYSTEM = 5

    Using Bluetooth was denied by the system. E.g. because of a system administrator policy.

  DENIED_BY_UNKNOWN = 6

    Permission to use Bluetooth was denied for an unknown reason.

  DENIED_BY_USER = 4

    The user denied permission for the app to use Bluetooth when prompted.

  NO_BLE_CENTRAL_ROLE = 2

    The Bluetooth radio does not support the Central role. (E.g. classic-only adapters.)

  NO_BLUETOOTH = 1

    The system does not support Bluetooth. I.e. there is no Bluetooth radio.

  POWERED_OFF = 3

    Bluetooth is not currently available because the radio is turned off.

  UNKNOWN = 7

    Bluetooth is not available for an unknown reason.

exception bleak.exc.BleakCharacteristicNotFoundError(char_specifier: int | str | UUID)

  Exception which is raised if a device does not support a characteristic.

  Added in version 0.22.

exception bleak.exc.BleakDBusError(dbus_error: str, error_body: list[Any])

  Specialized exception type for D-Bus errors.

  property dbus_error: str

    Gets the D-Bus error name, e.g. `org.freedesktop.DBus.Error.UnknownObject`.

  property dbus_error_details: str | None

    Gets the optional D-Bus error details, e.g. ‘Invalid UUID’.

exception bleak.exc.BleakDeviceNotFoundError(identifier: str, *args: object)

  Exception which is raised if a device can not be found by `connect`, `pair` and `unpair`. This is the case if the OS Bluetooth stack has never seen this device or it was removed and forgotten.

  Added in version 0.19.

exception bleak.exc.BleakError

  Base Exception for bleak.

exception bleak.exc.BleakGATTProtocolError(error_code: int)

  Exception which is raised if a GATT protocol error occurs.

  Added in version 3.0.

  property code: BleakGATTProtocolErrorCode

    Gets the GATT protocol error code.

class bleak.exc.BleakGATTProtocolErrorCode(*values)

  Enumeration of GATT protocol error codes.

  Added in version 3.0.

## Utilities

bleak.uuids.normalize_uuid_16(uuid: int) → str

  Normaizes a 16-bit integer UUID to the format used by Bleak.

  Returns:

    128-bit UUID as string with the format `"0000xxxx-0000-1000-8000-00805f9b34fb"`.

  Example:

      uuid = normalize_uuid_16(0x1234)
      # uuid == "00001234-0000-1000-8000-00805f9b34fb"

  Added in version 0.21.

bleak.uuids.normalize_uuid_32(uuid: int) → str

  Normaizes a 32-bit integer UUID to the format used by Bleak.

  Returns:

    128-bit UUID as string with the format `"xxxxxxxx-0000-1000-8000-00805f9b34fb"`.

  Example:

      uuid = normalize_uuid_32(0x12345678)
      # uuid == "12345678-0000-1000-8000-00805f9b34fb"

  Added in version 0.21.

bleak.uuids.normalize_uuid_str(uuid: str) → str

  Normaizes a UUID to the format used by Bleak.

  - Converted to lower case.

  - 16-bit and 32-bit UUIDs are expanded to 128-bit.

  Example:

      # 16-bit
      uuid1 = normalize_uuid_str("1234")
      # uuid1 == "00001234-0000-1000-8000-00805f9b34fb"

      # 32-bit
      uuid2 = normalize_uuid_str("12345678")
      # uuid2 == "12345678-0000-1000-8000-00805f9b34fb"

      # 128-bit
      uuid3 = normalize_uuid_str("12345678-0000-1234-1234-1234567890ABC")
      # uuid3 == "12345678-0000-1234-1234-1234567890abc"

  Added in version 0.20.

  Changed in version 0.21: Added support for 32-bit UUIDs.

bleak.uuids.register_uuids(uuids_to_descriptions: dict[str, str]) → None

  Add or modify the mapping of 128-bit UUIDs for services and characteristics to descriptions.

  Parameters:

    uuids_to_descriptions – A dictionary of new mappings