# Windows backend

The Windows backend of bleak is written using PyWinRT to provide bindings for the Windows Runtime (WinRT).

The Windows backend implements a `BleakClient` in the module `bleak.backends.winrt.client`, a `BleakScanner` method in the `bleak.backends.winrt.scanner` module. There are also backend-specific implementations of the `BleakGATTService`, `BleakGATTCharacteristic` and `BleakGATTDescriptor` classes.

## Specific features for the Windows backend

### Client

> - The constructor keyword `address_type` which can have the values `"public"` or `"random"`. This value makes sure that the connection is made in a fashion that suits the peripheral.

## API

### Utilities

bleak.backends.winrt.util.allow_sta() → None

  Suppress check for MTA thread type and allow STA.

  Bleak will hang forever if the current thread is not MTA - unless there is a Windows event loop running that is properly integrated with asyncio in Python.

  If your program meets that condition, you must call this function do disable the check for MTA. If your program doesn’t have a graphical user interface you probably shouldn’t call this function. and use `uninitialize_sta()` instead.

  Added in version 0.22.1.

async bleak.backends.winrt.util.assert_mta() → None

  Asserts that the current apartment type is MTA.

  Raises:

    BleakError – If the current apartment type is not MTA and there is no Windows message loop running.

  Added in version 0.22.

  Changed in version 0.22.2: Function is now async and will not raise if the current apartment type is STA and the Windows message loop is running.

bleak.backends.winrt.util.uninitialize_sta()

  Uninitialize the COM library on the current thread if it was not initialized as MTA.

  This is intended to undo the implicit initialization of the COM library as STA by packages like pywin32.

  It should be called as early as possible in your application after the offending package has been imported.

  Added in version 0.22.

### Scanner

class bleak.backends.winrt.scanner.BleakScannerWinRT(detection_callback: Callable[[BLEDevice, AdvertisementData], Coroutine[Any, Any, None] | None] | None, service_uuids: list[str] | None, scanning_mode: Literal['active', 'passive'], **kwargs: Any)

  The native Windows Bleak BLE Scanner.

  Implemented using Python/WinRT.

  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.

    - scanning_mode – Set to `"passive"` to avoid the `"active"` scanning mode.

  async start() → None

    Start scanning for devices

  async stop() → None

    Stop scanning for devices

class bleak.backends.winrt.scanner.RawAdvData(adv: winrt.windows.devices.bluetooth.advertisement.BluetoothLEAdvertisementReceivedEventArgs | None, scan: winrt.windows.devices.bluetooth.advertisement.BluetoothLEAdvertisementReceivedEventArgs | None)

  Platform-specific advertisement data.

  Windows does not combine advertising data with type SCAN_RSP with other advertising data like other platforms, so we have to do it ourselves.

  adv: winrt.windows.devices.bluetooth.advertisement.BluetoothLEAdvertisementReceivedEventArgs | None

    The advertisement data received from the BluetoothLEAdvertisementWatcher.Received event.

  scan: winrt.windows.devices.bluetooth.advertisement.BluetoothLEAdvertisementReceivedEventArgs | None

    The scan response for the same device as adv.

### Client

BLE Client for Windows 10 systems, implemented with WinRT.

class bleak.backends.winrt.client.BleakClientWinRT(address_or_ble_device: BLEDevice | str, services: set[str] | None = None, *, winrt: WinRTClientArgs, **kwargs: Any)

  Native Windows Bleak Client.

  Parameters:

    - address_or_ble_device (str or BLEDevice) – The Bluetooth address of the BLE peripheral to connect to or the `BLEDevice` object representing it.

    - services – Optional set of service UUIDs that will be used.

    - winrt (dict) – A dictionary of Windows-specific configuration values.

  async connect(pair: bool, **kwargs: Any) → None

    Connect to the specified GATT server.

    Keyword Arguments:

      timeout (float) – Timeout for required `BleakScanner.find_device_by_address` call.

  async disconnect() → None

    Disconnect from the specified GATT server.

  property is_connected: bool

    Check connection status between this client and the server.

    Returns:

      Boolean representing connection status.

  property mtu_size: int

    Get ATT MTU size for active connection

  property name: str

    See `bleak.BleakClient.name()`.

  async pair(**kwargs: Any) → None

    Attempts to pair with the device.

    Keyword Arguments:

      protection_level (int) –

      A `DevicePairingProtectionLevel` enum value:

      1. None - Pair the device using no levels of protection.

      2. Encryption - Pair the device using encryption.

      3. EncryptionAndAuthentication - Pair the device using encryption and authentication.

      Changed in version 1.0: Issues `DeprecationWarning` if used. The default behavior has changed and this argument should no longer be needed.

  async read_gatt_char(characteristic: BleakGATTCharacteristic, **kwargs: Any) → bytearray

    Perform read operation on the specified GATT characteristic.

    Parameters:

      characteristic (BleakGATTCharacteristic) – The characteristic to read from.

    Keyword Arguments:

      use_cached (bool) – `False` forces Windows to read the value from the device again and not use its own cached value. Defaults to `False`.

    Returns:

      (bytearray) The read data.

  async read_gatt_descriptor(descriptor: BleakGATTDescriptor, **kwargs: Any) → bytearray

    Perform read operation on the specified GATT descriptor.

    Parameters:

      descriptor – The descriptor to read from.

    Keyword Arguments:

      use_cached (bool) – False forces Windows to read the value from the device again and not use its own cached value. Defaults to False.

    Returns:

      The read data.

  async start_notify(characteristic: BleakGATTCharacteristic, callback: Callable[[bytearray], None], **kwargs: Any) → None

    Activate notifications/indications on a characteristic.

    Keyword Arguments:

      force_indicate (bool) – If this is set to True, then Bleak will set up a indication request instead of a notification request, given that the characteristic supports notifications as well as indications.

  async stop_notify(characteristic: BleakGATTCharacteristic) → None

    Deactivate notification/indication on a specified characteristic.

    Parameters:

      characteristic (BleakGATTCharacteristic) – The characteristic to deactivate notification/indication on.

  async unpair() → None

    Attempts to unpair from the device.

    N.B. unpairing also leads to disconnection in the Windows backend.

  async write_gatt_char(characteristic: BleakGATTCharacteristic, data: SizedBuffer, response: bool) → None

    Perform a write operation on the specified GATT characteristic.

    Parameters:

      - characteristic – The characteristic to write to.

      - data – The data to send.

      - response – If write-with-response operation should be done.

  async write_gatt_descriptor(descriptor: BleakGATTDescriptor, data: SizedBuffer) → None

    Perform a write operation on the specified GATT descriptor.

    Parameters:

      - descriptor – The descriptor to read from.

      - data – The data to send (any bytes-like object).

class bleak.backends.winrt.client.FutureLike(op: winrt.windows.foundation.IAsyncOperation.~T)

  Wraps a WinRT IAsyncOperation in a “future-like” object so that it can be passed to Python APIs.

  Needed until https://github.com/pywinrt/pywinrt/issues/14