BLE Device Connection Manager

A robust Bluetooth Low Energy device connection manager that implements comprehensive error handling for BLE operations.

Capabilities

Bluetooth Availability Check

The system must check if Bluetooth is available before attempting any BLE operations.

• When Bluetooth adapter is not available (no hardware), the system catches the appropriate exception and returns a structured error with error type "no_adapter" @test
• When Bluetooth is powered off, the system catches the appropriate exception and returns a structured error with error type "powered_off" @test

Device Discovery with Error Handling

The system must discover BLE devices and handle discovery failures appropriately.

• When a device with a specific address cannot be found, the system catches the appropriate exception and returns None @test
• When device discovery succeeds, it returns the device information @test

Characteristic Operations with Error Handling

The system must read device characteristics and handle characteristic-related errors.

• When attempting to read a characteristic that doesn't exist on the device, the system catches the appropriate exception and returns an error dict with "error" key set to "characteristic_not_found" @test
• When a characteristic is successfully read, it returns the characteristic value @test

Generic BLE Error Handling

The system must handle base BLE errors that don't fall into specific categories.

• When a generic BLE error occurs during an operation, the system catches the base exception type and returns an error dict with "error" key set to "ble_error" @test

Implementation

@generates

API

from typing import Optional, Dict, Any

def check_bluetooth_availability() -> Dict[str, Any]:
    """
    Check if Bluetooth is available on the system.

    Returns:
        Dict with 'available' (bool) and optionally 'error_type' (str) keys.
        Error types: 'no_adapter', 'powered_off', 'permission_denied'
    """
    pass

def find_device_by_address(address: str, timeout: float = 5.0) -> Optional[Dict[str, str]]:
    """
    Find a BLE device by its address.

    Args:
        address: The Bluetooth device address to find
        timeout: Discovery timeout in seconds

    Returns:
        Dict with device info ('address', 'name') if found, None if not found
    """
    pass

def read_device_characteristic(address: str, characteristic_uuid: str) -> Dict[str, Any]:
    """
    Connect to a device and read a characteristic value.

    Args:
        address: The Bluetooth device address
        characteristic_uuid: UUID of the characteristic to read

    Returns:
        Dict with 'success' (bool), and either 'value' (bytes) or 'error' (str)
        Error types: 'characteristic_not_found', 'ble_error', 'connection_failed'
    """
    pass

Dependencies { .dependencies }

bleak { .dependency }

Provides cross-platform Bluetooth Low Energy support with comprehensive exception handling.