Backend Management

def start(self):
    """
    Initialize and start the backend resources.
    
    For BGAPI: Opens serial connection to USB adapter
    For GATTTool: Starts gatttool subprocess and initializes CLI
    
    Raises:
        BGAPIError: BGAPI backend initialization failed
        BLEError: General backend startup failure
    """

def stop(self):
    """
    Stop and free all backend resources.
    
    Disconnects all active connections and cleans up background processes.
    Must be called to prevent resource leaks.
    """

def supports_unbonded(self) -> bool:
    """
    Check if backend supports unbonded (unauthenticated) communication.
    
    Returns:
        bool: True if unbonded communication supported
    """

def connect(self, address: str, timeout: float = 5.0, **kwargs) -> BLEDevice:
    """
    Connect to a BLE device by MAC address.
    
    Args:
        address: BLE MAC address (e.g., '01:23:45:67:89:ab')
        timeout: Connection timeout in seconds (default: 5.0)
        address_type: BLEAddressType.public or BLEAddressType.random
        **kwargs: Backend-specific connection parameters
    
    Returns:
        BLEDevice: Connected device instance
    
    Raises:
        NotConnectedError: Connection failed
        BLEError: General connection error
    """

import pygatt

adapter = pygatt.BGAPIBackend()
adapter.start()

# Connect with random address type
device = adapter.connect('01:23:45:67:89:ab', 
                        address_type=pygatt.BLEAddressType.random,
                        timeout=10.0)

# BGAPI-specific connection parameters
device = adapter.connect('01:23:45:67:89:ab',
                        interval_min=60,
                        interval_max=76,
                        supervision_timeout=100,
                        latency=0)

def scan(self, *args, **kwargs) -> list:
    """
    Perform BLE device scan to discover nearby devices.
    
    Args:
        timeout: Scan duration in seconds
        **kwargs: Backend-specific scan parameters
    
    Returns:
        list: List of discovered device dictionaries containing:
            - 'address': Device MAC address
            - 'name': Device name (may be None)
            - 'rssi': Signal strength
    
    Raises:
        BLEError: Scan operation failed
    """

def filtered_scan(self, name_filter: str = "", *args, **kwargs) -> list:
    """
    Scan for BLE devices and filter by device name.
    
    Args:
        name_filter: String that must be contained in device name
        **kwargs: Same as scan() method
    
    Returns:
        list: Filtered list of devices matching name filter
    """

import pygatt

adapter = pygatt.GATTToolBackend()
adapter.start()

# Basic scan
devices = adapter.scan(timeout=10)
for device in devices:
    print(f"Found: {device['address']} - {device['name']} (RSSI: {device['rssi']})")

# Filtered scan for specific device types
fitness_trackers = adapter.filtered_scan("Fitbit", timeout=10)

def clear_bond(self, address: str = None):
    """
    Clear stored bonding information for a device or all devices.
    
    Args:
        address: Specific device MAC address to unbond, or None for all devices
    
    Note:
        BGAPI: Clears bonds from adapter's internal storage
        GATTTool: Uses bluetoothctl to remove system-level bonds
    """

# Clear bond for specific device
adapter.clear_bond('01:23:45:67:89:ab')

# Clear all bonds
adapter.clear_bond()

adapter = pygatt.BGAPIBackend()

adapter = pygatt.GATTToolBackend()