{"id":6668,"library":"home-assistant-bluetooth","title":"Home Assistant Bluetooth","description":"Home Assistant Bluetooth provides Python models and helpers for integrating Bluetooth devices with Home Assistant. It acts as a wrapper around the `habluetooth` library to offer a consistent API. The current version is 2.0.0, and it follows a release cadence tied to Home Assistant development and dependency updates.","status":"active","version":"2.0.0","language":"en","source_language":"en","source_url":"https://github.com/home-assistant-libs/home-assistant-bluetooth","tags":["bluetooth","home assistant","asyncio","bleak","smart home","ble"],"install":[{"cmd":"pip install home-assistant-bluetooth","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"Core Bluetooth interface wrapper, providing native backend functionality.","package":"habluetooth"}],"imports":[{"symbol":"BluetoothServiceInfoBleak","correct":"from home_assistant_bluetooth import BluetoothServiceInfoBleak"},{"symbol":"BluetoothManager","correct":"from home_assistant_bluetooth import BluetoothManager"},{"symbol":"async_get_bluetooth_manager","correct":"from home_assistant_bluetooth import async_get_bluetooth_manager"}],"quickstart":{"code":"import asyncio\nfrom home_assistant_bluetooth import BluetoothManager, BluetoothServiceInfoBleak\n\nasync def main():\n    manager = BluetoothManager()\n    await manager.async_setup()\n\n    def advertisement_callback(service_info: BluetoothServiceInfoBleak):\n        print(f\"Advertisement: {service_info.name} ({service_info.address}) - RSSI: {service_info.rssi}\")\n        if service_info.service_data:\n            print(f\"  Service Data: {service_info.service_data}\")\n        if service_info.service_uuids:\n            print(f\"  Service UUIDs: {service_info.service_uuids}\")\n\n    manager.async_register_service_info_callback(advertisement_callback)\n\n    print(\"Listening for Bluetooth advertisements... Press Ctrl+C to stop.\")\n    try:\n        while True:\n            await asyncio.sleep(1) # Keep the manager running\n    except asyncio.CancelledError:\n        pass\n    finally:\n        await manager.async_stop()\n\nif __name__ == \"__main__\":\n    try:\n        asyncio.run(main())\n    except KeyboardInterrupt:\n        print(\"\\nStopped listening.\")","lang":"python","description":"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."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":">=2.0.0"},{"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`.","message":"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.","severity":"gotcha","affected_versions":"All"},{"fix":"Upgrade your Python environment to version 3.11 or later.","message":"The library explicitly requires Python 3.11 or newer. Running it on older Python versions will result in `ImportError` or other compatibility issues.","severity":"gotcha","affected_versions":"<=1.13.1"},{"fix":"Ensure your application uses `asyncio` for running the main loop and handling Bluetooth events. Familiarize yourself with Python's asynchronous programming model.","message":"The `BluetoothManager` and associated helpers are designed around `asyncio`. All interactions and callbacks are asynchronous, requiring proper `async` / `await` patterns.","severity":"gotcha","affected_versions":"All"}],"env_vars":null,"last_verified":"2026-04-15T00:00:00.000Z","next_check":"2026-07-14T00:00:00.000Z","problems":[]}