High availability Bluetooth

Warnings

• breaking Version 6.0.0 removes `BaseBleakScanner` inheritance from `HaBleakScannerWrapper` and the `register_detection_callback` method. Code relying on these old Bleak patterns will no longer work.
  Fix: Update `HaBleakScannerWrapper` usage to leverage the new async iterator patterns (e.g., `scanner.advertisement_data`) or `discovered_devices_and_advertisement_data` methods, as demonstrated in the quickstart. Direct callback registration is no longer supported.
• gotcha The `habluetooth` library requires Python 3.11 or newer. Installations or attempts to run on older Python versions will fail or result in compatibility errors.
  Fix: Ensure your development and deployment environments are running Python 3.11 or a more recent version. Consider using virtual environments to manage Python versions effectively.
• gotcha habluetooth maintains a rapid release cadence, often publishing multiple versions within a month. While this indicates active development, it means minor API adjustments or bug fixes can land frequently.
  Fix: For production or stable environments, consider pinning the `habluetooth` version in your `requirements.txt` to a specific minor version (e.g., `habluetooth~=6.0`) to avoid unexpected changes from newer releases. Regularly review the GitHub release notes before updating.

Install

• pip install habluetooth Install stable version

Imports

• BluetoothManager

  from habluetooth import BluetoothManager

• HaBleakScannerWrapper

  from habluetooth import HaBleakScannerWrapper

  While 'from habluetooth.scanner import HaBleakScannerWrapper' works, the class is re-exported at the top-level for convenience.

Quickstart

This quickstart demonstrates how to initialize the `BluetoothManager`, set up a `HaBleakScannerWrapper`, and asynchronously iterate over discovered Bluetooth devices and their advertisement data. Run this script to see local Bluetooth devices and their basic information.

import asyncio
from habluetooth import BluetoothManager, HaBleakScannerWrapper

async def main():
    manager = BluetoothManager()
    await manager.async_setup()
    scanner = HaBleakScannerWrapper(manager)

    print("Starting Bluetooth scan...")
    async with scanner:
        # Iterate over discovered devices and their advertisement data
        async for device, advertisement_data in scanner.advertisement_data:
            print(f"Device: {device.name or device.address}, RSSI: {advertisement_data.rssi}, Services: {advertisement_data.service_uuids}")
            # Uncomment the line below to stop after the first detected device
            # break
    await manager.async_stop()

if __name__ == "__main__":
    try:
        asyncio.run(main())
    except KeyboardInterrupt:
        print("Scan interrupted by user.")