# BleakClient class

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, winrt: WinRTClientArgs = {}, backend: type[BaseBleakClient] | None = None, **kwargs: Any)

  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.

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

## Connecting and disconnecting

Before doing anything else with a `BleakClient` object, it must be connected.

`bleak.BleakClient` is a an async context manager, so the recommended way of connecting is to use it as such:

    import asyncio
    from bleak import BleakClient

    async def main():
        async with BleakClient("XX:XX:XX:XX:XX:XX") as client:
            # Read a characteristic, etc.
            ...

        # Device will disconnect when block exits.
        ...

    # Using asyncio.run() is important to ensure that device disconnects on
    # KeyboardInterrupt or other unhandled exception.
    asyncio.run(main())

It is also possible to connect and disconnect without a context manager, however this can leave the device still connected when the program exits:

async BleakClient.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 BleakClient.disconnect() → None

  Disconnect from the specified GATT server.

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

The current connection status can be retrieved with:

property BleakClient.is_connected: bool

  Check connection status between this client and the GATT server.

  Returns:

    Boolean representing connection status.

A callback can be provided to the `BleakClient` constructor via the `disconnect_callback` argument to be notified of disconnection events.

## Device information

property BleakClient.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.

property BleakClient.address: str

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

property BleakClient.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 BleakClient.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.

## GATT Client Operations

All Bluetooth Low Energy devices use a common Generic Attribute Profile (GATT) for interacting with the device after it is connected. Some GATT operations like discovering the services/characteristic/descriptors and negotiating the MTU are handled automatically by Bleak and/or the OS Bluetooth stack.

The primary operations for the Bleak client are reading, writing and subscribing to characteristics.

### Services

The available services on a device are automatically enumerated when connecting to a device. Services describe the devices capabilities.

property BleakClient.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.

### GATT characteristics

Most I/O with a device is done via the characteristics.

async BleakClient.read_gatt_char(char_specifier: BleakGATTCharacteristic | int | str | UUID, **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.

  Returns:

    The read data.

  Raises:

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

    - backend-specific exceptions – if the read operation failed.

async BleakClient.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.

    - backend-specific exceptions – if the write operation failed.

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

  Example:

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

async BleakClient.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 BleakClient.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.

### GATT descriptors

Descriptors can provide additional information about a characteristic.

async BleakClient.read_gatt_descriptor(desc_specifier: BleakGATTDescriptor | int, **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.

  Raises:

    - BleakError – if the descriptor could not be found.

    - backend-specific exceptions – if the read operation failed.

  Returns:

    The read data.

async BleakClient.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.

    - backend-specific exceptions – if the read operation failed.

## Pairing/bonding

On some devices, some characteristics may require authentication in order to read or write the characteristic. In this case pairing/bonding the device is required.

Tip

If you need to pair the device before connecting, pass `pair=True` to the `BleakClient` constructor. Then pairing will happen during the connection process and you do not need to call the `pair` method explicitly.

async BleakClient.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 BleakClient.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`.