Welcome to Bleak Retry Connector documentation!

Installation & Usage

Project Info

Bleak Retry Connector

License

A connector for Bleak Clients that handles transient connection failures

Installation

Install this via pip (or your favourite package manager):

pip install bleak-retry-connector

Usage

Quick Start

Replace your direct BleakClient.connect() calls with establish_connection() for automatic retry logic and better error handling:

import asyncio
from bleak import BleakScanner
from bleak_retry_connector import establish_connection, BleakClientWithServiceCache

async def connect_to_device():
    # Find your device
    device = await BleakScanner.find_device_by_address("AA:BB:CC:DD:EE:FF")

    if device is None:
        print("Device not found!")
        return

    # Establish connection with automatic retry logic
    client = await establish_connection(
        BleakClientWithServiceCache,  # Use BleakClientWithServiceCache for service caching
        device,
        device.name or "Unknown Device",
        max_attempts=3  # Will retry up to 3 times with backoff
    )

    try:
        # Use the connected client normally
        services = client.services
        print(f"Connected! Found {len(list(services))} services")

        # Read a characteristic
        value = await client.read_gatt_char("00002a00-0000-1000-8000-00805f9b34fb")
        print(f"Read value: {value}")

    finally:
        await client.disconnect()

# Run the example
asyncio.run(connect_to_device())

Why Use bleak-retry-connector?

Automatic Retry Logic: Handles transient connection failures automatically
Intelligent Backoff: Uses appropriate delays between retry attempts
Service Caching: BleakClientWithServiceCache caches services for faster reconnections
Better Error Messages: Provides clear, actionable error messages
Platform-Specific Handling: Manages quirks across different operating systems
Connection Slot Management: Handles limited connection slots on some devices

Common Connection Issues This Solves

Device not found errors that resolve on retry
Connection timeouts on first attempt
“Out of connection slots” errors on ESP32 devices
Interference from other Bluetooth operations
Platform-specific connection quirks

For detailed documentation and advanced usage, see the full documentation.

Contributors ✨

Thanks goes to these wonderful people (emoji key):

This project follows the all-contributors specification. Contributions of any kind welcome!

Credits

This package was created with Cookiecutter and the browniebroke/cookiecutter-pypackage project template.