Home Assistant Bluetooth

Warnings

• breaking Version 2.0.0 introduced support for `bleak` 1.x, which is a key dependency of the underlying `habluetooth` library. If your system or other integrated components implicitly relied on `bleak` 0.x behavior or APIs, you may encounter breaking changes or compatibility issues after upgrading.
  Fix: Ensure your environment and the `habluetooth` dependency (and thus `bleak`) are compatible with `bleak` 1.x. Consult `habluetooth` documentation for specific `bleak` version requirements.
• gotcha This library, via its `habluetooth` dependency, relies on system-level Bluetooth libraries (e.g., `libbluetooth-dev` on Linux). You must have these installed on your operating system for `habluetooth` to compile and function correctly.
  Fix: Install necessary Bluetooth development packages for your OS. For Debian/Ubuntu: `sudo apt-get install libbluetooth-dev`. For Fedora: `sudo dnf install bluez-libs-devel`.
• gotcha The library explicitly requires Python 3.11 or newer. Running it on older Python versions will result in `ImportError` or other compatibility issues.
  Fix: Upgrade your Python environment to version 3.11 or later.
• gotcha The `BluetoothManager` and associated helpers are designed around `asyncio`. All interactions and callbacks are asynchronous, requiring proper `async` / `await` patterns.
  Fix: Ensure your application uses `asyncio` for running the main loop and handling Bluetooth events. Familiarize yourself with Python's asynchronous programming model.

Install

• pip install home-assistant-bluetooth Install latest version

Imports

• BluetoothServiceInfoBleak

  from home_assistant_bluetooth import BluetoothServiceInfoBleak

• BluetoothManager

  from home_assistant_bluetooth import BluetoothManager

• async_get_bluetooth_manager

  from home_assistant_bluetooth import async_get_bluetooth_manager

Quickstart

This quickstart demonstrates how to initialize the `BluetoothManager` and register a callback to receive Bluetooth advertisement data. It will continuously listen for advertisements until interrupted.

import asyncio
from home_assistant_bluetooth import BluetoothManager, BluetoothServiceInfoBleak

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

    def advertisement_callback(service_info: BluetoothServiceInfoBleak):
        print(f"Advertisement: {service_info.name} ({service_info.address}) - RSSI: {service_info.rssi}")
        if service_info.service_data:
            print(f"  Service Data: {service_info.service_data}")
        if service_info.service_uuids:
            print(f"  Service UUIDs: {service_info.service_uuids}")

    manager.async_register_service_info_callback(advertisement_callback)

    print("Listening for Bluetooth advertisements... Press Ctrl+C to stop.")
    try:
        while True:
            await asyncio.sleep(1) # Keep the manager running
    except asyncio.CancelledError:
        pass
    finally:
        await manager.async_stop()

if __name__ == "__main__":
    try:
        asyncio.run(main())
    except KeyboardInterrupt:
        print("\nStopped listening.")