Bluetooth


The Bluetooth integration will detect nearby Bluetooth devices. Discovered devices will show up in the discovered section on the integrations page in the configuration panel.

Configuration

Adding Bluetooth to your Home Assistant instance can be done via the user interface, by using this My button:

Manual configuration steps

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

# Example configuration.yaml entry
bluetooth:

D-Bus and BlueZ are required on Linux

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.

  • Home Assistant Operating System: no additional steps are required. Home Assistant OS version 8.4 or later is recommended for performance reasons.
  • Home Assistant Container: The host system must run BlueZ, and the D-Bus socket must be accessible to Home Assistant inside the container.
  • Home Assistant Supervised: The host system must run BlueZ, and the D-Bus socket must be accessible to Home Assistant inside the container.
  • Home Assistant Core: The system must run BlueZ, and the D-Bus socket must be accessible to Home Assistant.

Additional details for Container installs

Making the DBus socket available in the Docker container

Additional details for Container and Supervised installs

Installing BlueZ

Installing a USB Bluetooth Adapter

Some systems may not come with Bluetooth and require a USB adapter. Installing an adapter for the first time may require multiple restarts for the device to be fully recognized.

If you experience an unreliable Bluetooth connection, installing a short USB extension cable between your Bluetooth adapter and your Home Assistant server may improve reliability.

Known working adapters

  • ASUS USB-BT400
  • ASUS USB-BT500
  • Avantree DG45
  • Kinivo BTD-400
  • Maxuni BT-501
  • SUMEE BT501
  • UGREEN CM390
  • XDO BT802 (Long Range)
  • ZEXMTE BT-505 (Long Range)
  • ZEXMTE BT-DG54

Unsupported adapters

  • tp-link UB400 - Frequent connection failures
  • tp-link UB500 - Frequent connection failures

Options

Options for Bluetooth can be set via the user interface, by taking the following steps:

  • Browse to your Home Assistant instance.
  • In the sidebar click on Settings.
  • From the configuration menu select: Devices & Services.
  • If multiple instances of Bluetooth are configured, choose the instance you want to configure.
  • Click on “Options”.

Multiple adapters

Support for multiple Bluetooth adapters is available on Linux systems only. Select the adapter you wish to use via the options flow on the integrations page. The adapter selection only affects integrations that use the Bluetooth integration interfaces.

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.yaml, 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.

Bluetooth interference with other devices

Devices that are using the 2.4 GHz band, like Wi-Fi, Zigbee, and USB3 devices (and their cable connections) are known to affect Bluetooth reception. Especially external SSD drives with USB3 cables are known to block the Bluetooth signal. Also, metal casings can decrease the Bluetooth performance of internal Bluetooth Adapters.

The following tips may improve reception of the Bluetooth Adapter:

  • Try to place USB3 devices (SSD, etc.) as far away as possible from your Bluetooth Adapter, e.g., by using an extension cable.
  • Use a USB3 extension cable with proper shielding and ferrite clamps.
  • Use a (good quality) external Bluetooth adapter with an antenna.