Registry / communication / home-assistant-bluetooth

home-assistant-bluetooth

library2.0.0pypypi✓ verified 84d ago

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.

communication

pip install home-assistant-bluetooth

github ↗package ↗changelog ↗

INSTALL

IMPORT

SIG · HOME-ASSISTANT-BLU

home-assistant-bluetooth

communicationpythonv2.0.0

Install

7.8s avg

Import

374ms

Disk

39MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v1.11.0 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.920 runs

installs and imports cleanly · install 0.0s · import 0.391s · 51.3MB

glibc

py 3.10–3.920 runs

installs and imports cleanly · install 7.8s · import 0.356s · 49MB

39MB installed

● package 39MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

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

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.")

Debug

Known issues

breakingVersion 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.

affects: >=2.0.0

gotchaThis 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`.

affects: All

gotchaThe 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.

affects: <=1.13.1

gotchaThe `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.

affects: All

Errors

Common errors & fixes

Failed to start Bluetooth: adapter 'hci0' not found

Home Assistant cannot detect or initialize the Bluetooth adapter, often due to hardware issues, incorrect permissions, or the Bluetooth service not running on the host system, especially in Docker or VM environments.

fix

Ensure the Bluetooth adapter is plugged in, powered on, and recognized by the host OS. For Docker, grant `NET_ADMIN` and `NET_RAW` capabilities to the container and ensure `/run/dbus` is mapped. For VMs, ensure the USB Bluetooth adapter is passed through correctly. Restart the host's Bluetooth service (`sudo service bluetooth restart` or `sudo systemctl restart bluetooth`).

ModuleNotFoundError: No module named 'bluetooth'

The Python environment where Home Assistant or `home-assistant-bluetooth` is running is missing the necessary system-level Bluetooth development libraries (e.g., `bluez-dev`, `libbluetooth-dev`). This is common in custom Python installations or Docker containers without appropriate host packages.

fix

Install the required Bluetooth development packages on your host system or inside your Docker container (if applicable). For Debian/Ubuntu-based systems, use `sudo apt-get install bluetooth bluez libbluetooth-dev libudev-dev`. For other distributions, find equivalent packages.

AttributeError: 'HaBleakScannerWrapper' object has no attribute 'find_device_by_address'

Developers are attempting to use `find_device_by_address` or similar direct `bleak` scanner methods on the `home-assistant-bluetooth` wrapper object, but these specific methods are not directly exposed or implemented in the `HaBleakScannerWrapper`.

fix

Instead of directly using `BleakScanner.find_device_by_address`, use the Home Assistant Bluetooth APIs, specifically `bluetooth.async_get_discovered_device_by_address` or similar functions provided by the `home-assistant-bluetooth` library, which handle device discovery and management within the Home Assistant context.

AttributeError: 'NoneType' object has no attribute 'product'

This error typically occurs during the initialization of the Bluetooth integration when an attempt is made to access properties (like 'product') of a Bluetooth adapter that Home Assistant or the underlying `habluetooth` library failed to properly detect or identify, resulting in a `None` object.

fix

This often points to a deeper issue with adapter detection or driver loading. Ensure the Bluetooth adapter is fully supported by the host OS and Home Assistant (check documentation for known working adapters). Try updating host OS kernel and Bluetooth drivers, rebooting the entire host system, or providing more specific hardware details in your Home Assistant configuration if possible. Sometimes, physically reconnecting a USB adapter helps.

Upgrade

Version history

2.0.0latest on PyPI · released Jul 9, 2025

Audit

Dependencies

habluetoothrequiredCore Bluetooth interface wrapper, providing native backend functionality.

Agent activity

25 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/home-assistant-libs/home-assistant-bluetooth ↗

packagehttps://pypi.org/project/home-assistant-bluetooth/ ↗

changeloghttps://github.com/home-assistant-libs/home-assistant-bluetooth/blob/main/CHANGELOG.md ↗