{"id":5135,"library":"bleak-retry-connector","title":"bleak-retry-connector","description":"bleak-retry-connector is a Python library that provides a robust wrapper around Bleak clients, adding automatic reconnection, service caching, and improved error handling for transient Bluetooth LE connection failures. It's built on top of the `bleak` library and is currently at version 4.6.0, with a fairly active release cadence, often updating dependencies and patching bugs.","status":"active","version":"4.6.0","language":"en","source_language":"en","source_url":"https://github.com/bluetooth-devices/bleak-retry-connector","tags":["bluetooth","BLE","bleak","retry","connection","automation","asynchronous"],"install":[{"cmd":"pip install bleak-retry-connector","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"Core Bluetooth LE communication library that bleak-retry-connector wraps and enhances.","package":"bleak","optional":false},{"reason":"Used for managing Bluetooth adapters and their states.","package":"bluetooth-adapters","optional":false}],"imports":[{"note":"This is the recommended class as it includes both retry logic and service caching, wrapping `BleakClientWithRetry`.","symbol":"BleakClientWithServiceCache","correct":"from bleak_retry_connector import BleakClientWithServiceCache"},{"note":"Use this if you only need retry logic without service caching. `BleakClientWithServiceCache` internally uses this.","symbol":"BleakClientWithRetry","correct":"from bleak_retry_connector import BleakClientWithRetry"}],"quickstart":{"code":"import asyncio\nfrom bleak_retry_connector import BleakClientWithServiceCache\n\nasync def connect_and_read(device_address: str):\n    try:\n        # Ensure you replace 'DEVICE_MAC_ADDRESS_OR_UUID' with an actual device address\n        # For example: 'XX:XX:XX:XX:XX:XX' (MAC) or 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx' (UUID)\n        # A real device with a known characteristic UUID is required to run this.\n        async with BleakClientWithServiceCache(device_address) as client:\n            if client.is_connected:\n                print(f\"Connected to {device_address}\")\n                # Example: List services\n                for service in client.services:\n                    print(f\"  Service: {service.uuid}\")\n                    for char in service.characteristics:\n                        print(f\"    Characteristic: {char.uuid}\")\n                        if \"read\" in char.properties:\n                            try:\n                                value = await client.read_gatt_char(char.uuid)\n                                print(f\"      Value: {value.hex()}\")\n                            except Exception as e:\n                                print(f\"      Could not read characteristic {char.uuid}: {e}\")\n            else:\n                print(f\"Failed to connect to {device_address} after retries.\")\n    except Exception as e:\n        print(f\"An error occurred: {e}\")\n\n# Replace with a real Bluetooth LE device address\n# This example is illustrative and requires a discoverable device.\nDEVICE_ADDRESS = \"XX:XX:XX:XX:XX:XX\" # Placeholder, replace with actual MAC or UUID\n\nif __name__ == \"__main__\":\n    print(\"Attempting to connect to a BLE device. This requires an actual device and may take time.\")\n    print(\"Please replace 'XX:XX:XX:XX:XX:XX' with your device's MAC address or UUID.\")\n    asyncio.run(connect_and_read(DEVICE_ADDRESS))\n","lang":"python","description":"This quickstart demonstrates how to connect to a Bluetooth LE device using `BleakClientWithServiceCache`. It attempts to connect, and if successful, lists its services and tries to read from available characteristics. Remember to replace `DEVICE_ADDRESS` with an actual MAC address or UUID of a nearby BLE device. The retry mechanism is handled automatically by the client."},"warnings":[{"fix":"Ensure your Python environment is 3.10 or higher. Upgrade Python if necessary.","message":"This library requires Python 3.10 or newer. Using older Python versions will result in installation or runtime errors.","severity":"gotcha","affected_versions":"<4.0.0"},{"fix":"Verify the correct MAC address or UUID of your target BLE device. Ensure the device is powered on, advertising, and within range.","message":"The `device_address` parameter expects a valid Bluetooth MAC address (e.g., 'XX:XX:XX:XX:XX:XX') or a UUID. Providing an incorrect format or an address for a device that is not discoverable will lead to connection failures.","severity":"gotcha","affected_versions":"All"},{"fix":"Consult the `bleak` documentation for platform-specific setup and troubleshooting. Ensure Bluetooth services are running correctly on your operating system.","message":"As a wrapper around `bleak`, `bleak-retry-connector` inherits platform-specific quirks and requirements, such as D-Bus availability on Linux or specific macOS/Windows OS versions. Connection issues can often stem from underlying OS Bluetooth service problems.","severity":"gotcha","affected_versions":"All"},{"fix":"Use a dedicated virtual environment for your project to isolate dependencies. Check the `pyproject.toml` or `setup.cfg` of `bleak-retry-connector` for exact dependency ranges and try to resolve conflicts manually or report to maintainers.","message":"Strict dependency ranges for `bleak` and `bluetooth-adapters` are enforced. If you have other packages that require different major versions of these dependencies, you might encounter version conflicts.","severity":"breaking","affected_versions":"All"}],"env_vars":null,"last_verified":"2026-04-13T00:00:00.000Z","next_check":"2026-07-12T00:00:00.000Z"}