# bleak package

## Subpackages

- bleak.args package
  - Submodules
  - bleak.args.bluez module
    - BlueZ backend arguments
    - `BlueZClientArgs`
      - `BlueZClientArgs.adapter`
    - `BlueZDiscoveryFilters`
      - `BlueZDiscoveryFilters.Discoverable`
      - `BlueZDiscoveryFilters.DuplicateData`
      - `BlueZDiscoveryFilters.Pathloss`
      - `BlueZDiscoveryFilters.Pattern`
      - `BlueZDiscoveryFilters.RSSI`
      - `BlueZDiscoveryFilters.Transport`
      - `BlueZDiscoveryFilters.UUIDs`
    - `BlueZNotifyArgs`
      - `BlueZNotifyArgs.use_start_notify`
    - `BlueZScannerArgs`
      - `BlueZScannerArgs.adapter`
      - `BlueZScannerArgs.filters`
      - `BlueZScannerArgs.or_patterns`
    - `OrPattern`
      - `OrPattern.ad_data_type`
      - `OrPattern.content_of_pattern`
      - `OrPattern.start_position`
  - bleak.args.corebluetooth module
    - CoreBluetooth backend arguments
    - `CBScannerArgs`
      - `CBScannerArgs.use_bdaddr`
    - `CBStartNotifyArgs`
      - `CBStartNotifyArgs.notification_discriminator`
  - bleak.args.winrt module
    - WinRT backend arguments
    - `WinRTClientArgs`
      - `WinRTClientArgs.address_type`
      - `WinRTClientArgs.use_cached_services`
  - Module contents
    - `SizedBuffer`
- bleak.backends package
  - Subpackages
    - bleak.backends.bluezdbus package
      - Submodules
      - bleak.backends.bluezdbus.advertisement_monitor module
      - bleak.backends.bluezdbus.client module
      - bleak.backends.bluezdbus.defs module
      - bleak.backends.bluezdbus.manager module
      - bleak.backends.bluezdbus.scanner module
      - bleak.backends.bluezdbus.signals module
      - bleak.backends.bluezdbus.utils module
      - bleak.backends.bluezdbus.version module
      - Module contents
    - bleak.backends.corebluetooth package
      - Submodules
      - bleak.backends.corebluetooth.CentralManagerDelegate module
      - bleak.backends.corebluetooth.PeripheralDelegate module
      - bleak.backends.corebluetooth.client module
      - bleak.backends.corebluetooth.scanner module
      - bleak.backends.corebluetooth.utils module
      - Module contents
    - bleak.backends.p4android package
      - Submodules
      - bleak.backends.p4android.client module
      - bleak.backends.p4android.defs module
      - bleak.backends.p4android.scanner module
      - bleak.backends.p4android.utils module
      - Module contents
    - bleak.backends.winrt package
      - Submodules
      - bleak.backends.winrt.client module
      - bleak.backends.winrt.scanner module
      - bleak.backends.winrt.util module
      - Module contents
  - Submodules
  - bleak.backends.characteristic module
    - `BleakGATTCharacteristic`
      - `BleakGATTCharacteristic.add_descriptor()`
      - `BleakGATTCharacteristic.description`
      - `BleakGATTCharacteristic.descriptors`
      - `BleakGATTCharacteristic.get_descriptor()`
      - `BleakGATTCharacteristic.handle`
      - `BleakGATTCharacteristic.max_write_without_response_size`
      - `BleakGATTCharacteristic.properties`
      - `BleakGATTCharacteristic.service_handle`
      - `BleakGATTCharacteristic.service_uuid`
      - `BleakGATTCharacteristic.uuid`
    - `GattCharacteristicsFlags`
      - `GattCharacteristicsFlags.authenticated_signed_writes`
      - `GattCharacteristicsFlags.broadcast`
      - `GattCharacteristicsFlags.extended_properties`
      - `GattCharacteristicsFlags.indicate`
      - `GattCharacteristicsFlags.notify`
      - `GattCharacteristicsFlags.read`
      - `GattCharacteristicsFlags.reliable_write`
      - `GattCharacteristicsFlags.writable_auxiliaries`
      - `GattCharacteristicsFlags.write`
      - `GattCharacteristicsFlags.write_without_response`
  - bleak.backends.client module
    - `BaseBleakClient`
      - `BaseBleakClient.connect()`
      - `BaseBleakClient.disconnect()`
      - `BaseBleakClient.is_connected`
      - `BaseBleakClient.mtu_size`
      - `BaseBleakClient.name`
      - `BaseBleakClient.pair()`
      - `BaseBleakClient.read_gatt_char()`
      - `BaseBleakClient.read_gatt_descriptor()`
      - `BaseBleakClient.set_disconnected_callback()`
      - `BaseBleakClient.start_notify()`
      - `BaseBleakClient.stop_notify()`
      - `BaseBleakClient.unpair()`
      - `BaseBleakClient.write_gatt_char()`
      - `BaseBleakClient.write_gatt_descriptor()`
    - `get_platform_client_backend_type()`
  - bleak.backends.descriptor module
    - `BleakGATTDescriptor`
      - `BleakGATTDescriptor.characteristic_handle`
      - `BleakGATTDescriptor.characteristic_uuid`
      - `BleakGATTDescriptor.description`
      - `BleakGATTDescriptor.handle`
      - `BleakGATTDescriptor.uuid`
  - bleak.backends.device module
    - `BLEDevice`
      - `BLEDevice.address`
      - `BLEDevice.details`
      - `BLEDevice.name`
  - bleak.backends.scanner module
    - `AdvertisementData`
      - `AdvertisementData.local_name`
      - `AdvertisementData.manufacturer_data`
      - `AdvertisementData.platform_data`
      - `AdvertisementData.rssi`
      - `AdvertisementData.service_data`
      - `AdvertisementData.service_uuids`
      - `AdvertisementData.tx_power`
    - `AdvertisementDataCallback`
    - `AdvertisementDataFilter`
    - `BaseBleakScanner`
      - `BaseBleakScanner.call_detection_callbacks()`
      - `BaseBleakScanner.create_or_update_device()`
      - `BaseBleakScanner.is_allowed_uuid()`
      - `BaseBleakScanner.register_detection_callback()`
      - `BaseBleakScanner.seen_devices`
      - `BaseBleakScanner.start()`
      - `BaseBleakScanner.stop()`
    - `get_platform_scanner_backend_type()`
  - bleak.backends.service module
    - `BleakGATTService`
      - `BleakGATTService.add_characteristic()`
      - `BleakGATTService.characteristics`
      - `BleakGATTService.description`
      - `BleakGATTService.get_characteristic()`
      - `BleakGATTService.handle`
      - `BleakGATTService.uuid`
    - `BleakGATTServiceCollection`
      - `BleakGATTServiceCollection.add_characteristic()`
      - `BleakGATTServiceCollection.add_descriptor()`
      - `BleakGATTServiceCollection.add_service()`
      - `BleakGATTServiceCollection.characteristics`
      - `BleakGATTServiceCollection.descriptors`
      - `BleakGATTServiceCollection.get_characteristic()`
      - `BleakGATTServiceCollection.get_descriptor()`
      - `BleakGATTServiceCollection.get_service()`
      - `BleakGATTServiceCollection.services`
  - Module contents
    - `BleakBackend`
      - `BleakBackend.BLUEZ_DBUS`
      - `BleakBackend.CORE_BLUETOOTH`
      - `BleakBackend.P4ANDROID`
      - `BleakBackend.PYTHONISTA_CB`
      - `BleakBackend.WIN_RT`
    - `get_default_backend()`

## Submodules

## bleak.assigned_numbers module

### Bluetooth Assigned Numbers

This module contains useful assigned numbers from the Bluetooth spec.

See <https://www.bluetooth.com/specifications/assigned-numbers/>.

class bleak.assigned_numbers.AdvertisementDataType(*values)

  Bases: `IntEnum`

  Generic Access Profile advertisement data types.

  Source <https://btprodspecificationrefs.blob.core.windows.net/assigned-numbers/Assigned%20Number%20Types/Generic%20Access%20Profile.pdf>.

  Added in version 0.15.

  CLASS_OF_DEVICE = 13
  COMPLETE_LIST_SERVICE_UUID128 = 7
  COMPLETE_LIST_SERVICE_UUID16 = 3
  COMPLETE_LIST_SERVICE_UUID32 = 5
  COMPLETE_LOCAL_NAME = 9
  FLAGS = 1
  INCOMPLETE_LIST_SERVICE_UUID128 = 6
  INCOMPLETE_LIST_SERVICE_UUID16 = 2
  INCOMPLETE_LIST_SERVICE_UUID32 = 4
  MANUFACTURER_SPECIFIC_DATA = 255
  SERVICE_DATA_UUID128 = 33
  SERVICE_DATA_UUID16 = 22
  SERVICE_DATA_UUID32 = 32
  SHORTENED_LOCAL_NAME = 8
  TX_POWER_LEVEL = 10

bleak.assigned_numbers.gatt_char_props_to_strs(props: int) → frozenset[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']]

  Convert a GATT characteristic properties bitmask to a set of strings.

  Parameters:

    props – The GATT characteristic properties bitmask.

  Returns:

    A set of strings representing the GATT characteristic properties.

## bleak.exc module

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

  Bases: `BleakError`

  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)

  Bases: `Enum`

  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)

  Bases: `BleakError`

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

  Added in version 0.22.

  char_specifier: int | str | UUID

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

  Bases: `BleakError`

  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)

  Bases: `BleakError`

  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.

  identifier: str

exception bleak.exc.BleakError

  Bases: `Exception`

  Base Exception for bleak.

exception bleak.exc.BleakGATTProtocolError(error_code: int)

  Bases: `BleakError`

  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)

  Bases: `IntEnum`

  Enumeration of GATT protocol error codes.

  Added in version 3.0.

  ATTRIBUTE_NOT_FOUND = 10
  ATTRIBUTE_NOT_LONG = 11
  CCCD_IMPROPERLY_CONFIGURED = 253
  DATABASE_OUT_OF_SYNC = 18
  INSUFFICIENT_AUTHENTICATION = 5
  INSUFFICIENT_AUTHORIZATION = 8
  INSUFFICIENT_ENCRYPTION = 15
  INSUFFICIENT_ENCRYPTION_KEY_SIZE = 12
  INSUFFICIENT_RESOURCE = 17
  INVALID_ATTRIBUTE_VALUE_LENGTH = 13
  INVALID_HANDLE = 1
  INVALID_OFFSET = 7
  INVALID_PDU = 4
  OUT_OF_RANGE = 255
  PREPARE_QUEUE_FULL = 9
  PROCEDURE_ALREADY_IN_PROGRESS = 254
  READ_NOT_PERMITTED = 2
  REQUEST_NOT_SUPPORTED = 6
  UNLIKELY_ERROR = 14
  UNSUPPORTED_GROUP_TYPE = 16
  VALUE_NOT_ALLOWED = 19
  WRITE_NOT_PERMITTED = 3
  WRITE_REQUEST_REJECTED = 252

## bleak.uuids module

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

bleak.uuids.uuidstr_to_str(uuid_: str) → str

## Module contents

Top-level package for bleak.

class bleak.BleakClient(address_or_ble_device: BLEDevice | str, disconnected_callback: Callable[[BleakClient], None] | None = None, services: Iterable[str] | None = None, *, timeout: float = 30, pair: bool = False, bluez: BlueZClientArgs = {}, winrt: WinRTClientArgs = {}, backend: type[BaseBleakClient] | None = None, **kwargs: Any)

  Bases: `object`

  The Client interface for connecting to a specific BLE GATT server and communicating with it.

  A BleakClient can be used as an asynchronous context manager in which case it automatically connects and disconnects.

  How many BLE connections can be active simultaneously, and whether connections can be active while scanning depends on the Bluetooth adapter hardware.

  Parameters:

    - address_or_ble_device – A `BLEDevice` received from a `BleakScanner` or a Bluetooth address (device UUID on macOS).

    - disconnected_callback – Callback that will be scheduled in the event loop when the client is disconnected. The callable must take one argument, which will be this client object.

    - services – Optional list of services to filter. If provided, only these services will be resolved. This may or may not reduce the time needed to enumerate the services depending on if the OS supports such filtering in the Bluetooth stack or not (should affect Windows and Mac). These can be 16-bit or 128-bit UUIDs.

    - timeout – Timeout in seconds passed to the implicit `discover` call when `address_or_ble_device` is not a `BLEDevice`. Defaults to 30.

    - pair – Attempt to pair with the the device before connecting, if it is not already paired. This has no effect on macOS since pairing is initiated automatically when accessing a characteristic that requires authentication. In rare cases, on other platforms, it might be necessary to pair the device first in order to be able to even enumerate the services during the connection process.

    - bluez – Dictionary of BlueZ/Linux platform-specific options.

    - winrt – Dictionary of WinRT/Windows platform-specific options.

    - backend – Used to override the automatically selected backend (i.e. for a custom backend).

    - **kwargs – Additional keyword arguments for backwards compatibility.

  Tip

  If you enable pairing with the `pair` argument, you will also want to extend the timeout to allow enough time for the user to find and enter the PIN code on the device, if required.

  Warning

  Although example code frequently initializes `BleakClient` with a Bluetooth address for simplicity, it is not recommended to do so for more complex use cases. There are several known issues with providing a Bluetooth address as the `address_or_ble_device` argument.

  1. macOS does not provide access to the Bluetooth address for privacy/ security reasons. Instead it creates a UUID for each Bluetooth device which is used in place of the address on this platform.

  2. Providing an address or UUID instead of a `BLEDevice` causes the `connect()` method to implicitly call `BleakScanner.discover()`. This is known to cause problems when trying to connect to multiple devices at the same time.

  Changed in version 0.15: `disconnected_callback` is no longer keyword-only. Added `winrt` parameter.

  Changed in version 0.18: No longer is alias for backend type and no longer inherits from `BaseBleakClient`. Added `backend` parameter.

  Changed in version 1.0: Added `pair` parameter.

  Changed in version 2.1.1: Changed default connect timeout from 10 to 30 seconds.

  Changed in version 3.0: Added `bluez` parameter.

  property address: str

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

  property backend_id: BleakBackend | str

    Gets the identifier of the backend in use.

    The value is one of the `BleakBackend` enum values in case of built-in backends, or a string identifying a custom backend.

    Added in version 2.0.

  async connect(**kwargs: Any) → None

    Connect to the specified GATT server.

    Parameters:

      **kwargs – For backwards compatibility - should not be used.

    Changed in version 1.0: No longer returns `True`. Instead, the return type is `None`.

  async disconnect() → None

    Disconnect from the specified GATT server.

    Changed in version 1.0: No longer returns `True`. Instead, the return type is `None`.

  property is_connected: bool

    Check connection status between this client and the GATT server.

    Returns:

      Boolean representing connection status.

  property mtu_size: int

    Gets the negotiated MTU size in bytes for the active connection.

    Consider using `bleak.backends.characteristic.BleakGATTCharacteristic.max_write_without_response_size` instead.

    Warning

    The BlueZ backend will always return 23 (the minimum MTU size). See the `mtu_size.py` example for a way to hack around this.

  property name: str

    Gets a human-readable name for the peripheral device.

    The name can be somewhat OS-dependent. It is usually the name provided by the standard Device Name characteristic, if present or the name provided by the advertising data. If neither is available, it will be a Bluetooth address separated with dashes (`-`) instead of colons (`:`) (or a UUID on Apple devices). It may also be possible to override the device name using the OS’s Bluetooth settings.

    Added in version 1.1.

  async pair(*args: Any, **kwargs: Any) → None

    Pair with the specified GATT server.

    This method is not available on macOS. Instead of manually initiating paring, the user will be prompted to pair the device the first time that a characteristic that requires authentication is read or written. This method may have backend-specific additional keyword arguments.

    Changed in version 1.0: No longer returns `True`. Instead, the return type is `None`.

  async read_gatt_char(char_specifier: BleakGATTCharacteristic | int | str | UUID, *, use_cached: bool = False, **kwargs: Any) → bytearray

    Perform read operation on the specified GATT characteristic.

    Parameters:

      - char_specifier – The characteristic to read from, specified by either integer handle, UUID or directly by the BleakGATTCharacteristic object representing it.

      - use_cached – If `True`, the cached value will be returned instead of performing a new read operation. May be ignored by some backends.

    Returns:

      The read data.

    Raises:

      - BleakCharacteristicNotFoundError – if a characteristic with the handle or UUID specified by `char_specifier` could not be found.

      - BleakGATTProtocolError – if the peripheral replied with ATT_ERROR_RSP.

      - backend-specific exceptions – in rare cases

    Changed in version 3.0: Now raises `BleakGATTProtocolError` when possible instead of backend-specific exceptions.

  async read_gatt_descriptor(desc_specifier: BleakGATTDescriptor | int, *, use_cached: bool = False, **kwargs: Any) → bytearray

    Perform read operation on the specified GATT descriptor.

    Parameters:

      - desc_specifier – The descriptor to read from, specified by either integer handle or directly by the BleakGATTDescriptor object representing it.

      - use_cached – If `True`, the cached value will be returned instead of performing a new read operation. May be ignored by some backends.

    Returns:

      The read data.

    Raises:

      - BleakError – if the descriptor could not be found.

      - BleakGATTProtocolError – if the peripheral replied with ATT_ERROR_RSP.

      - backend-specific exceptions – in rare cases.

    Changed in version 3.0: Now raises `BleakGATTProtocolError` when possible instead of backend-specific exceptions.

  property services: BleakGATTServiceCollection

    Gets the collection of GATT services available on the device.

    The returned value is only valid as long as the device is connected.

    Raises:

      BleakError – if service discovery has not been performed yet during this connection.

  async start_notify(char_specifier: BleakGATTCharacteristic | int | str | UUID, callback: Callable[[BleakGATTCharacteristic, bytearray], None | Awaitable[None]], *, bluez: BlueZNotifyArgs = {}, cb: CBStartNotifyArgs = {}, **kwargs: Any) → None

    Activate notifications/indications on a characteristic.

    Callbacks must accept two inputs. The first will be the characteristic and the second will be a `bytearray` containing the data received.

        def callback(sender: BleakGATTCharacteristic, data: bytearray):
            print(f"{sender}: {data}")

        client.start_notify(char_uuid, callback)

    Parameters:

      - char_specifier – The characteristic to activate notifications/indications on a characteristic, specified by either integer handle, UUID or directly by the BleakGATTCharacteristic object representing it.

      - callback – The function to be called on notification. Can be regular function or async function.

      - bluez – BlueZ backend-specific arguments.

      - cb – CoreBluetooth backend-specific arguments.

    Raises:

      - BleakCharacteristicNotFoundError – if a characteristic with the handle or UUID specified by `char_specifier` could not be found.

      - backend-specific exceptions – if the start notification operation failed.

    Changed in version 0.18: The first argument of the callback is now a `BleakGATTCharacteristic` instead of an `int`.

    Changed in version 1.0: Added the `cb` parameter.

    Changed in version 2.1: Added the `bluez` parameter.

  async stop_notify(char_specifier: BleakGATTCharacteristic | int | str | UUID) → None

    Deactivate notification/indication on a specified characteristic.

    Parameters:

      char_specifier – The characteristic to deactivate notification/indication on, specified by either integer handle, UUID or directly by the BleakGATTCharacteristic object representing it.

    Raises:

      - BleakCharacteristicNotFoundError – if a characteristic with the handle or UUID specified by `char_specifier` could not be found.

      - backend-specific exceptions – if the stop notification operation failed.

    Tip

    Notifications are stopped automatically on disconnect, so this method does not need to be called unless notifications need to be stopped some time before the device disconnects.

  async unpair() → None

    Unpair from the specified GATT server.

    Unpairing will also disconnect the device.

    This method is only available on Windows and Linux and will raise an exception on other platforms.

    Changed in version 1.0: No longer returns `True`. Instead, the return type is `None`.

  async write_gatt_char(char_specifier: BleakGATTCharacteristic | int | str | UUID, data: SizedBuffer, response: bool | None = None) → None

    Perform a write operation on the specified GATT characteristic.

    There are two possible kinds of writes. Write with response (sometimes called a Request) will write the data then wait for a response from the remote device. Write without response (sometimes called Command) will queue data to be written and return immediately.

    Each characteristic may support one kind or the other or both or neither. Consult the device’s documentation or inspect the properties of the characteristic to find out which kind of writes are supported.

    Parameters:

      - char_specifier – The characteristic to write to, specified by either integer handle, UUID or directly by the `BleakGATTCharacteristic` object representing it. If a device has more than one characteristic with the same UUID, then attempting to use the UUID wil fail and a characteristic object must be used instead.

      - data – The data to send. When a write-with-response operation is used, the length of the data is limited to 512 bytes. When a write-without-response operation is used, the length of the data is limited to `max_write_without_response_size`. Any type that supports the buffer protocol can be passed.

      - response – If `True`, a write-with-response operation will be used. If `False`, a write-without-response operation will be used. Omitting the argument is deprecated and may raise a warning. If this arg is omitted, the default behavior is to check the characteristic properties to see if the “write” property is present. If it is, a write-with-response operation will be used. Note: some devices may incorrectly report or omit the property, which is why an explicit argument is encouraged.

    Raises:

      - BleakCharacteristicNotFoundError – if a characteristic with the handle or UUID specified by `char_specifier` could not be found.

      - BleakGATTProtocolError – if the peripheral replied with ATT_ERROR_RSP. Only applies when `response=True`.

      - backend-specific exceptions – in rare cases.

    Changed in version 0.21: The default behavior when `response=` is omitted was changed.

    Changed in version 3.0: Now raises `BleakGATTProtocolError` when possible instead of backend-specific exceptions.

    Example:

        MY_CHAR_UUID = "1234"
        ...
        await client.write_gatt_char(MY_CHAR_UUID, b"\x00\x01\x02\x03", response=True)

  async write_gatt_descriptor(desc_specifier: BleakGATTDescriptor | int, data: SizedBuffer) → None

    Perform a write operation on the specified GATT descriptor.

    Parameters:

      - desc_specifier – The descriptor to write to, specified by either integer handle directly by the BleakGATTDescriptor object representing it.

      - data – The data to send.

    Raises:

      - BleakError – if the descriptor could not be found.

      - ValueError – if attempting to write to the Client Characteristic Configuration Descriptor (CCCD, UUID 0x2902).

      - BleakGATTProtocolError – if the peripheral replied with ATT_ERROR_RSP.

      - backend-specific exceptions – in rare cases.

    Changed in version 3.0: Now raises `ValueError` when attempting to write to the CCCD instead of backend-specific exceptions.

    Changed in version 3.0: Now raises `BleakGATTProtocolError` when possible instead of backend-specific exceptions.

class bleak.BleakScanner(detection_callback: Callable[[BLEDevice, AdvertisementData], Coroutine[Any, Any, None] | None] | None = None, service_uuids: list[str] | None = None, scanning_mode: Literal['active', 'passive'] = 'active', *, bluez: BlueZScannerArgs = {}, cb: CBScannerArgs = {}, backend: type[BaseBleakScanner] | None = None, **kwargs: Any)

  Bases: `object`

  Interface for Bleak Bluetooth LE Scanners.

  The scanner will listen for BLE advertisements, optionally filtering on advertised services or other conditions, and collect a list of `BLEDevice` objects. These can subsequently be used to connect to the corresponding BLE server.

  A `BleakScanner` can be used as an asynchronous context manager in which case it automatically starts and stops scanning.

  Parameters:

    - detection_callback – Optional function that will be called each time a device is discovered or advertising data has changed.

    - service_uuids – Optional list of service UUIDs to filter on. Only advertisements containing this advertising data will be received. Required on macOS >= 12.0, < 12.3 (unless you create an app with `py2app`).

    - scanning_mode – Set to `"passive"` to avoid the `"active"` scanning mode. Passive scanning is not supported on macOS! Will raise `BleakError` if set to `"passive"` on macOS.

    - bluez – Dictionary of arguments specific to the BlueZ backend.

    - cb – Dictionary of arguments specific to the CoreBluetooth backend.

    - backend – Used to override the automatically selected backend (i.e. for a custom backend).

    - **kwargs – Additional args for backwards compatibility.

  Tip

  The first received advertisement in `detection_callback` may or may not include scan response data if the remote device supports it. Be sure to take this into account when handing the callback. For example, the scan response often contains the local name of the device so if you are matching a device based on other data but want to display the local name to the user, be sure to wait for `adv_data.local_name is not None`.

  Changed in version 0.15: `detection_callback`, `service_uuids` and `scanning_mode` are no longer keyword-only. Added `bluez` parameter.

  Changed in version 0.18: No longer is alias for backend type and no longer inherits from `BaseBleakScanner`. Added `backend` parameter.

  Changed in version 3.0: Deprecated `adapter` keyword argument. Use `bluez` argument instead with `{"adapter": "<adapter_name>"}`.

  class ExtraArgs

    Bases: `TypedDict`

    Keyword args from `BleakScanner` that can be passed to other convenience methods.

    adapter: str

      Name of adapter to use (BlueZ specific), e.g. hci0.

      Changed in version 3.0: This argument is deprecated and will be removed in a future release. Use the `bluez` argument with `{"adapter": "<adapter_name>"}` instead.

    backend: type[BaseBleakScanner]

      Used to override the automatically selected backend (i.e. for a custom backend).

    bluez: BlueZScannerArgs

      Dictionary of arguments specific to the BlueZ backend.

    cb: CBScannerArgs

      Dictionary of arguments specific to the CoreBluetooth backend.

    scanning_mode: Literal['active', 'passive']

      Set to `"passive"` to avoid the `"active"` scanning mode. Passive scanning is not supported on macOS! Will raise `BleakError` if set to `"passive"` on macOS.

    service_uuids: list[str]

      Optional list of service UUIDs to filter on. Only advertisements containing this advertising data will be received. Required on macOS >= 12.0, < 12.3 (unless you create an app with `py2app`).

  async advertisement_data() → AsyncGenerator[tuple[BLEDevice, AdvertisementData], None]

    Yields devices and associated advertising data packets as they are discovered.

    Note

    Ensure that scanning is started before calling this method.

    Returns:

      An async iterator that yields tuples (`BLEDevice`, `AdvertisementData`).

    Added in version 0.21.

  property backend_id: BleakBackend | str

    Gets the identifier of the backend in use.

    The value is one of the `BleakBackend` enum values in case of built-in backends, or a string identifying a custom backend.

    Added in version 2.0.

  async classmethod discover(timeout: float = 5.0, *, return_adv: Literal[False] = False, **kwargs: Unpack[ExtraArgs]) → list[BLEDevice]
  async classmethod discover(timeout: float = 5.0, *, return_adv: Literal[True], **kwargs: Unpack[ExtraArgs]) → dict[str, tuple[BLEDevice, AdvertisementData]]

    Scan continuously for `timeout` seconds and return discovered devices.

    Parameters:

      - timeout – Time, in seconds, to scan for.

      - return_adv – If `True`, the return value will include advertising data.

      - **kwargs – Additional arguments will be passed to the `BleakScanner` constructor.

    Returns:

      The value of `discovered_devices_and_advertisement_data` if `return_adv` is `True`, otherwise the value of `discovered_devices`.

    Changed in version 0.19: Added `return_adv` parameter.

  property discovered_devices: list[BLEDevice]

    Gets list of the devices that the scanner has discovered during the scanning.

    If you also need advertisement data, use `discovered_devices_and_advertisement_data` instead.

  property discovered_devices_and_advertisement_data: dict[str, tuple[BLEDevice, AdvertisementData]]

    Gets a map of device address to tuples of devices and the most recently received advertisement data for that device.

    The address keys are useful to compare the discovered devices to a set of known devices. If you don’t need to do that, consider using `discovered_devices_and_advertisement_data.values()` to just get the values instead.

    Added in version 0.19.

  async classmethod find_device_by_address(device_identifier: str, timeout: float = 10.0, **kwargs: Unpack[ExtraArgs]) → BLEDevice | None

    Obtain a `BLEDevice` for a BLE server specified by Bluetooth address or (macOS) UUID address.

    Parameters:

      - device_identifier – The Bluetooth/UUID address of the Bluetooth peripheral sought.

      - timeout – Optional timeout to wait for detection of specified peripheral before giving up. Defaults to 10.0 seconds.

      - **kwargs – additional args passed to the `BleakScanner` constructor.

    Returns:

      The `BLEDevice` sought or `None` if not detected.

  async classmethod find_device_by_filter(filterfunc: AdvertisementDataFilter, timeout: float = 10.0, **kwargs: Unpack[ExtraArgs]) → BLEDevice | None

    Obtain a `BLEDevice` for a BLE server that matches a given filter function.

    This can be used to find a BLE server by other identifying information than its address, for example its name.

    Parameters:

      - filterfunc – A function that is called for every BLEDevice found. It should return `True` only for the wanted device.

      - timeout – Optional timeout to wait for detection of specified peripheral before giving up. Defaults to 10.0 seconds.

      - **kwargs – Additional arguments to be passed to the `BleakScanner` constructor.

    Returns:

      The `BLEDevice` sought or `None` if not detected before the timeout.

  async classmethod find_device_by_name(name: str, timeout: float = 10.0, **kwargs: Unpack[ExtraArgs]) → BLEDevice | None

    Obtain a `BLEDevice` for a BLE server specified by the local name in the advertising data.

    Parameters:

      - name – The name sought.

      - timeout – Optional timeout to wait for detection of specified peripheral before giving up. Defaults to 10.0 seconds.

      - **kwargs – additional args passed to the `BleakScanner` constructor.

    Returns:

      The `BLEDevice` sought or `None` if not detected.

    Added in version 0.20.

  async start() → None

    Start scanning for devices.

    Raises:

      BleakBluetoothNotAvailableError – if Bluetooth is not currently available

    Changed in version 2.0: Now raises `BleakBluetoothNotAvailableError` instead of `BleakError` when Bluetooth is not currently available.

  async stop() → None

    Stop scanning for devices