Bluetooth
The Bluetooth integrationIntegrations connect and integrate Home Assistant with your devices, services, and more. [Learn more] supports Bluetooth Low Energy devices. Bluetooth Classic devices are not supported. Compatible devices discovered nearby appear on Settings > Devices & services.
This page documents the Bluetooth integration. To learn more about Bluetooth in Home Assistant, refer to Bluetooth.
Configuration
To add the Bluetooth integration to your Home Assistant instance, use this My button:
Manual configuration steps
If the above My button doesn’t work, you can also perform the following steps manually:
-
Browse to your Home Assistant instance.
-
In the bottom right corner, select the
Add Integration button. -
From the list, select Bluetooth.
-
Follow the instructions on screen to complete the setup.
Configuration
While this integration is part of default_config: to enable automatic discovery of the Bluetooth Adapter, it will only be enabled by setting up the configuration flow, or manually adding it to your configuration.yamlThe configuration.yaml file is the main configuration file for Home Assistant. It lists the integrations to be loaded and their specific configurations. In some cases, the configuration needs to be edited manually directly in the configuration.yaml file. Most integrations can be configured in the UI. [Learn more] file.
After changing the configuration.yamlThe configuration.yaml file is the main configuration file for Home Assistant. It lists the integrations to be loaded and their specific configurations. In some cases, the configuration needs to be edited manually directly in the configuration.yaml file. Most integrations can be configured in the UI. [Learn more] file, restart Home Assistant to apply the changes.
# Example configuration.yaml entry
bluetooth:
Requirements for Linux systems
For Bluetooth to function on Linux systems:
- The D-Bus socket must be accessible to Home Assistant.
- The Bluetooth adapter must be accessible to D-Bus and running BlueZ >= 5.43. It is highly recommended to use BlueZ >= 5.63 as older versions have been reported to be unreliable.
- The D-Bus implementation should be dbus-broker.
- The host system should be running Linux kernel 5.15.62 or later.
Additional requirements by install method
- Home Assistant Operating System: Upgrade to Home Assistant OS version 9.0 or later. All Bluetooth requirements are automatically configured.
- Home Assistant Container: The host system must run BlueZ, and the D-Bus socket must be accessible to Home Assistant inside the container. Additional configuration is required (see below).
Additional details for Container
You only need these configuration steps for Home Assistant Container installations. Home Assistant Operating System automatically handles all Bluetooth configuration. To check your installation type, go to Settings > About and look for Installation method.
Container configuration for Bluetooth
Home Assistant Container requires specific configuration to access Bluetooth adapters.
Required capabilities:
Add the following Linux capabilities to your container configuration to enable full Bluetooth management:
Docker Compose:
cap_add:
- NET_ADMIN
- NET_RAW
volumes:
- /run/dbus:/run/dbus:ro
Docker run:
docker run --cap-add=NET_ADMIN --cap-add=NET_RAW -v /run/dbus:/run/dbus:ro ...
D-Bus socket:
For most systems, the D-Bus socket is in /run/dbus. You need to make the socket available in the container for Home Assistant to connect to D-Bus and access the Bluetooth adapter. If the D-Bus socket is in /var/run/dbus on your host system, use -v /var/run/dbus:/run/dbus:ro instead.
What happens without these capabilities:
If NET_ADMIN and NET_RAW capabilities are missing:
- Your Bluetooth will operate in a degraded mode with limited functionality
- Automatic adapter recovery is unavailable - your adapters cannot be reset when they stop responding
- Connection parameters and management API commands will fail
- Raw advertising data will be missing, causing unreliable updates for your devices
- An error will appear in your logs: “Missing required permissions for Bluetooth management”
Switching from dbus-daemon to dbus-broker
Follow the instructions to switch to dbus-broker.
Installing BlueZ
On Debian based host systems, the sudo apt-get -y install bluez command will install BlueZ.
Configuration options
- In Home Assistant, go to Settings > Connectivity > Bluetooth.
- Select Adapters.
- On the adapter of interest, select the
cogwheel icon, then select your options. - Not all adapters have configuration options. If you don’t see a cogwheel icon, your adapter does not support configuration options.
- Under Scanning mode, pick Auto, Active, or Passive. For what each mode does, refer to Scanning modes.
Troubleshooting
Bluetooth adapter requires additional permissions
Symptom: “Bluetooth adapter requires additional permissions”
Under Settings > System > Repairs, you see a repair saying that your Bluetooth adapter is operating in degraded mode, because your container needs additional permissions.
Description
Home Assistant can use your Bluetooth adapter, but only with limited functions. For example, it can’t reset an adapter that stops responding, and updates from your devices can be less reliable. This happens when Home Assistant runs in a container that doesn’t have the permissions it needs to manage Bluetooth.
Resolution
- Go to Settings > About and check the Installation method.
- If it says Home Assistant Container or Unsupported Third Party Container, add the required permissions to your container. Follow the steps in Additional details for Container, then recreate the container with the new settings. For example, with Docker Compose, run
docker compose up -d. Restarting the container isn’t enough, because Docker only applies the new permissions when it creates the container. - If it says Home Assistant OS or Home Assistant Supervised, you don’t need to change any permissions yourself, because they’re set up automatically. If you still see the repair, report the issue and include your system information.
For problems with your Bluetooth connections, such as slow connections or interference, refer to Troubleshooting Bluetooth connections.
Integrations that require exclusive use of the Bluetooth Adapter
While newer integrations can share the Bluetooth Adapter, some legacy integrations require exclusive use of the adapter. Enabling this integration may prevent an integration that has not been updated to use newer methods from functioning.
Deleting the config entry for this integration will release control of the adapter and allow another integration to gain exclusive use of the Bluetooth adapter. If you have manually added bluetooth: to your configuration.yamlThe configuration.yaml file is the main configuration file for Home Assistant. It lists the integrations to be loaded and their specific configurations. In some cases, the configuration needs to be edited manually directly in the configuration.yaml file. Most integrations can be configured in the UI. [Learn more], you must also remove it to prevent the configuration from being recreated. Consider adding a second Bluetooth adapter on Linux systems if you need to continue using legacy integrations, as more integrations will move to use the Bluetooth integration in the future.
Discovered integrations
The following integrations are automatically discovered by the Bluetooth integration:
- Acaia
- Airthings BLE
- Aranet
- BlueMaestro
- BTHome
- Dormakaba dKey
- eQ-3 Bluetooth Smart Thermostats
- EufyLife
- Fjäråskupan
- Gardena Bluetooth
- Govee Bluetooth
- HomeKit Device
- Husqvarna Automower BLE
- iBeacon Tracker
- IKEA Idasen Desk
- Improv via BLE
- INKBIRD
- IronOS
- Kegtron
- Keymitt MicroBot Push
- Kuler Sky
- La Marzocco
- LD2410 BLE
- LED BLE
- Medcom Bluetooth
- Melnor Bluetooth
- Moat
- Mopeka
- Motionblinds Bluetooth
- Oral-B
- Probe Plus
- Qingping
- RAPT Bluetooth
- Ruuvi BLE
- Sensirion BLE
- SensorPro
- SensorPush
- Snooz
- SwitchBot Bluetooth
- ThermoBeacon
- ThermoPro
- Tilt Hydrometer BLE
- Xiaomi BLE
- Yale Access Bluetooth