{"id":10352,"library":"winrt-windows-devices-bluetooth-genericattributeprofile","title":"WinRT Windows.Devices.Bluetooth.GenericAttributeProfile","description":"This package is a Python projection of the Windows Runtime (WinRT) APIs specific to `Windows.Devices.Bluetooth.GenericAttributeProfile`. It allows Python applications to interact with Bluetooth LE devices and their Generic Attribute Profile (GATT) services and characteristics on Windows. Part of the `pywinrt` project, it is currently at version 3.2.1 and receives regular updates to align with Windows SDK changes and project enhancements.","status":"active","version":"3.2.1","language":"en","source_language":"en","source_url":"https://github.com/pywinrt/pywinrt","tags":["Windows","WinRT","Bluetooth","GATT","UWP","IoT","Hardware"],"install":[{"cmd":"pip install winrt-windows-devices-bluetooth-genericattributeprofile","lang":"bash","label":"Install specific GATT package"},{"cmd":"pip install winrt","lang":"bash","label":"Install all WinRT projections (recommended for most users)"}],"dependencies":[{"reason":"Provides core WinRT projection functionalities and infrastructure required by all specific WinRT projection packages.","package":"winrt-runtime"}],"imports":[{"note":"WinRT projection imports follow the 'winrt.<namespace>' pattern, not the PyPI package name directly.","wrong":"from winrt_windows_devices_bluetooth_genericattributeprofile import GattDeviceService","symbol":"GattDeviceService","correct":"from winrt.windows.devices.bluetooth.genericattributeprofile import GattDeviceService"},{"note":"Classes are imported from their specific namespace. BluetoothLEDevice is in 'winrt.windows.devices.bluetooth', not 'genericattributeprofile'.","wrong":"from winrt.windows.devices.bluetooth.genericattributeprofile import BluetoothLEDevice","symbol":"BluetoothLEDevice","correct":"from winrt.windows.devices.bluetooth import BluetoothLEDevice"},{"note":"DeviceInformation is part of the enumeration namespace, which is separate from bluetooth namespaces.","wrong":"from winrt.windows.devices.bluetooth import DeviceInformation","symbol":"DeviceInformation","correct":"from winrt.windows.devices.enumeration import DeviceInformation"}],"quickstart":{"code":"import asyncio\nfrom winrt.windows.devices.bluetooth import BluetoothLEDevice\nfrom winrt.windows.devices.enumeration import DeviceInformation\n\nasync def list_bluetooth_le_devices():\n    # AQS filter for Bluetooth LE devices\n    aqs_le_devices = BluetoothLEDevice.get_device_selector()\n    \n    print(\"Searching for Bluetooth LE devices (this may take a few seconds)...\")\n    # DeviceInformation is in winrt.windows.devices.enumeration\n    devices = await DeviceInformation.find_all_async(aqs_le_devices)\n    \n    if not devices:\n        print(\"No Bluetooth LE devices found.\")\n        print(\"Ensure Bluetooth is enabled and devices are discoverable.\")\n        return\n\n    print(f\"Found {len(devices)} Bluetooth LE devices:\")\n    for i, device in enumerate(devices):\n        print(f\"  [{i}] Name: {device.name}, Id: {device.id}\")\n        # To get GATT services, you would then obtain a BluetoothLEDevice instance\n        # and call its GetGattServicesAsync method.\n        # Example (conceptual):\n        # from winrt.windows.devices.bluetooth.genericattributeprofile import GattCommunicationStatus\n        # le_device = await BluetoothLEDevice.from_id_async(device.id)\n        # if le_device:\n        #     result = await le_device.get_gatt_services_async()\n        #     if result.status == GattCommunicationStatus.SUCCESS:\n        #         for service in result.services:\n        #             print(f\"      GATT Service: {service.uuid}\")\n        #             # Further GATT operations would use objects from \n        #             # winrt.windows.devices.bluetooth.genericattributeprofile\n        #             # e.g., GattDeviceService, GattCharacteristic, etc.\n\nif __name__ == \"__main__\":\n    # This code must run on a Windows machine with Bluetooth enabled and permissions granted.\n    asyncio.run(list_bluetooth_le_devices())\n","lang":"python","description":"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."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":"<3.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":"<3.2.0"},{"fix":"Upgrade to `pywinrt` 3.2.0 or later to utilize the `winrt.system.hresult` module for standardized error code handling.","message":"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`.","severity":"gotcha","affected_versions":"<3.2.0"},{"fix":"Upgrade to `pywinrt` version 3.2.1 or later to mitigate potential circular import issues.","message":"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.","severity":"gotcha","affected_versions":"<3.2.1"}],"env_vars":null,"last_verified":"2026-04-17T00:00:00.000Z","next_check":"2026-07-16T00:00:00.000Z","problems":[{"fix":"Change `import windows.devices.bluetooth` to `import winrt.windows.devices.bluetooth`.","cause":"Incorrect top-level import. WinRT projection namespaces are always prefixed with `winrt.`.","error":"ModuleNotFoundError: No module named 'windows.devices.bluetooth'"},{"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.","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.","error":"AttributeError: 'IAsyncOperation_1__GattDeviceServicesResult' object has no attribute 'get'"},{"fix":"Correct the import path to `from winrt.windows.devices.bluetooth.genericattributeprofile import GattDeviceService`.","cause":"Importing directly from the PyPI package name (using underscores) instead of the structured WinRT namespace (using dots) within the `winrt` module.","error":"ImportError: cannot import name 'GattDeviceService' from 'winrt_windows_devices_bluetooth_genericattributeprofile'"},{"fix":"Upgrade `pywinrt` to version 3.2.0 or later to enable access to the `winrt.system.hresult` module.","cause":"Accessing the `winrt.system.hresult` module, which contains WinRT error codes, on a `pywinrt` version older than 3.2.0.","error":"AttributeError: module 'winrt.system' has no attribute 'hresult'"}]}