WinRT Windows.Devices.Bluetooth.GenericAttributeProfile

Common errors

• ModuleNotFoundError: No module named 'windows.devices.bluetooth'

  cause Incorrect top-level import. WinRT projection namespaces are always prefixed with `winrt.`.
  fix Change `import windows.devices.bluetooth` to `import winrt.windows.devices.bluetooth`.

• AttributeError: 'IAsyncOperation_1__GattDeviceServicesResult' object has no attribute 'get'

  cause Attempting to call `.get()` or `.wait()` on an asynchronous WinRT operation (`IAsyncOperation` or `IAsyncAction`) on a `pywinrt` version older than 3.2.0, where these methods were not available or stable.
  fix Upgrade `pywinrt` to version 3.2.0 or later. Alternatively, use `await` on the async operation within an `async` function if synchronous blocking behavior is not strictly required.

• ImportError: cannot import name 'GattDeviceService' from 'winrt_windows_devices_bluetooth_genericattributeprofile'

  cause Importing directly from the PyPI package name (using underscores) instead of the structured WinRT namespace (using dots) within the `winrt` module.
  fix Correct the import path to `from winrt.windows.devices.bluetooth.genericattributeprofile import GattDeviceService`.

• AttributeError: module 'winrt.system' has no attribute 'hresult'

  cause Accessing the `winrt.system.hresult` module, which contains WinRT error codes, on a `pywinrt` version older than 3.2.0.
  fix Upgrade `pywinrt` to version 3.2.0 or later to enable access to the `winrt.system.hresult` module.

Warnings

• breaking Version 3.0.0 introduced significant breaking changes, including a redesigned API, new `winrt.runtime` module, and changes to `winrt.system` functionalities (e.g., `box_...`/`unbox_...` functions, `Object.as_()`). Applications targeting `pywinrt` v2.x.x will require migration.
  Fix: Refer to the official migration guide for v2 to v3 on the pywinrt GitHub repository (scripts/2to3/README.md). Update import paths and API calls as necessary.
• gotcha Prior to version 3.2.0, synchronously calling WinRT async operations was less straightforward, primarily relying on `asyncio.run()` or `await` within an async context. Directly calling `.get()` or `.wait()` on async operations was not officially supported or stable.
  Fix: For synchronous execution of async operations, upgrade to `pywinrt` 3.2.0 or later and use the `.get()` or `.wait()` methods on the returned `IAsyncOperation` or `IAsyncAction` objects. Otherwise, ensure all async calls are `await`ed within an `async` function.
• gotcha The `winrt.system.hresult` module, which provides access to common WinRT error codes, was introduced in version 3.2.0. Attempting to access this module or its contents on older versions will result in an `AttributeError`.
  Fix: Upgrade to `pywinrt` 3.2.0 or later to utilize the `winrt.system.hresult` module for standardized error code handling.
• gotcha Fixed a possible circular import exception in version 3.2.1. Older versions might encounter issues related to module loading order, especially in complex application structures.
  Fix: Upgrade to `pywinrt` version 3.2.1 or later to mitigate potential circular import issues.

Install

• pip install winrt-windows-devices-bluetooth-genericattributeprofile Install specific GATT package
• pip install winrt Install all WinRT projections (recommended for most users)

Imports

• GattDeviceService
  wrong:

  from winrt_windows_devices_bluetooth_genericattributeprofile import GattDeviceService

  correct:

  from winrt.windows.devices.bluetooth.genericattributeprofile import GattDeviceService

  WinRT projection imports follow the 'winrt.<namespace>' pattern, not the PyPI package name directly.
• BluetoothLEDevice
  wrong:

  from winrt.windows.devices.bluetooth.genericattributeprofile import BluetoothLEDevice

  correct:

  from winrt.windows.devices.bluetooth import BluetoothLEDevice

  Classes are imported from their specific namespace. BluetoothLEDevice is in 'winrt.windows.devices.bluetooth', not 'genericattributeprofile'.
• DeviceInformation
  wrong:

  from winrt.windows.devices.bluetooth import DeviceInformation

  correct:

  from winrt.windows.devices.enumeration import DeviceInformation

  DeviceInformation is part of the enumeration namespace, which is separate from bluetooth namespaces.

Quickstart

This quickstart demonstrates how to use `pywinrt` to list available Bluetooth LE devices on a Windows system. It shows the basic pattern for importing WinRT classes and calling asynchronous methods. To interact with GATT services (e.g., GattDeviceService), you would extend this by getting a specific `BluetoothLEDevice` and calling its `GetGattServicesAsync` method, which is conceptually shown in comments.

import asyncio
from winrt.windows.devices.bluetooth import BluetoothLEDevice
from winrt.windows.devices.enumeration import DeviceInformation

async def list_bluetooth_le_devices():
    # AQS filter for Bluetooth LE devices
    aqs_le_devices = BluetoothLEDevice.get_device_selector()
    
    print("Searching for Bluetooth LE devices (this may take a few seconds)...")
    # DeviceInformation is in winrt.windows.devices.enumeration
    devices = await DeviceInformation.find_all_async(aqs_le_devices)
    
    if not devices:
        print("No Bluetooth LE devices found.")
        print("Ensure Bluetooth is enabled and devices are discoverable.")
        return

    print(f"Found {len(devices)} Bluetooth LE devices:")
    for i, device in enumerate(devices):
        print(f"  [{i}] Name: {device.name}, Id: {device.id}")
        # To get GATT services, you would then obtain a BluetoothLEDevice instance
        # and call its GetGattServicesAsync method.
        # Example (conceptual):
        # from winrt.windows.devices.bluetooth.genericattributeprofile import GattCommunicationStatus
        # le_device = await BluetoothLEDevice.from_id_async(device.id)
        # if le_device:
        #     result = await le_device.get_gatt_services_async()
        #     if result.status == GattCommunicationStatus.SUCCESS:
        #         for service in result.services:
        #             print(f"      GATT Service: {service.uuid}")
        #             # Further GATT operations would use objects from 
        #             # winrt.windows.devices.bluetooth.genericattributeprofile
        #             # e.g., GattDeviceService, GattCharacteristic, etc.

if __name__ == "__main__":
    # This code must run on a Windows machine with Bluetooth enabled and permissions granted.
    asyncio.run(list_bluetooth_le_devices())