Bluetooth Device Pairing Manager

A Python utility for managing Bluetooth Low Energy (BLE) device pairings, focusing on device cleanup and connection management.

Overview

Build a command-line tool that allows users to connect to a BLE device, verify the connection, and then unpair the device to clean up system pairing records. This is useful for testing workflows, device reset scenarios, or managing temporary device connections.

Requirements

Core Functionality

The tool should:

1. Accept a Bluetooth device address as a command-line argument
2. Scan for and locate the specified BLE device
3. Establish a connection to the device
4. Verify the connection is active
5. Unpair the device and disconnect
6. Report the status of each operation

Device Discovery

• The tool should be able to find a BLE device by its address within a reasonable timeout (10 seconds)
• If the device is not found, the tool should report an error and exit gracefully

Connection Management

• Once a device is found, establish a connection to it
• Verify that the connection is successful before proceeding
• Handle connection failures appropriately with clear error messages

Unpairing

• After successfully connecting, unpair the device from the system
• The unpair operation should also disconnect the device
• Confirm that the unpair operation completed successfully

Error Handling

• Provide clear error messages for each failure scenario:
  • Device not found
  • Connection failed
  • Unpair operation failed
  • Bluetooth adapter not available
• Exit with appropriate status codes (0 for success, non-zero for errors)

Test Cases

• When provided with an address of a device that is advertising, the tool successfully finds, connects to, and unpairs the device @test
• When provided with an address of a non-existent device, the tool reports that the device was not found within the timeout period @test
• When the connection to a device fails, the tool reports a connection error without attempting to unpair @test

Implementation

@generates

API

import asyncio
from typing import Optional

async def find_device(address: str, timeout: float = 10.0) -> Optional[object]:
    """
    Scan for a BLE device with the specified address.

    Args:
        address: The Bluetooth address of the device to find
        timeout: Maximum time in seconds to scan for the device

    Returns:
        Device object if found, None otherwise
    """
    pass

async def connect_device(device: object) -> bool:
    """
    Connect to a BLE device.

    Args:
        device: The device object to connect to

    Returns:
        True if connection successful, False otherwise
    """
    pass

async def unpair_device(client: object) -> bool:
    """
    Unpair and disconnect from a BLE device.

    Args:
        client: The connected client object

    Returns:
        True if unpair successful, False otherwise
    """
    pass

async def main(device_address: str) -> int:
    """
    Main function to orchestrate the find, connect, and unpair workflow.

    Args:
        device_address: Bluetooth address of the device to manage

    Returns:
        Exit code (0 for success, 1 for failure)
    """
    pass

if __name__ == "__main__":
    import sys
    if len(sys.argv) != 2:
        print("Usage: python unpair_manager.py <device_address>")
        sys.exit(1)

    exit_code = asyncio.run(main(sys.argv[1]))
    sys.exit(exit_code)

Dependencies { .dependencies }

bleak { .dependency }

Provides cross-platform Bluetooth Low Energy GATT client functionality for scanning, connecting, and managing BLE device pairings.

@satisfied-by