2025.3.4
首页 ▸ Integrations ▸

蓝牙

蓝牙 integration集成将 Home Assistant 与您的设备、服务等连接和集成。 [Learn more] 将检测附近的蓝牙设备。发现的设备将显示在配置面板的集成页面的发现部分。

配置

要将 蓝牙 集成 添加到您的 Home Assistant 实例中，请使用此 My 按钮：

手动配置步骤

如果上述 My 按钮不起作用，您也可以手动执行以下步骤：

在开始之前

在许多情况下，使用 ESP32 的蓝牙代理比直接连接的适配器或卡更好，因为 Linux 内核的更新之前曾破坏蓝牙功能，而蓝牙驱动在 Linux 上的支持通常落后于其他操作系统对于新适配器的支持。对于虚拟化实例的用户来说，蓝牙代理尤其有趣，因为 USB 直通可能会导致额外的问题。更多信息请参见下面的远程适配器部分，或访问 ESPhome 的 蓝牙代理页面。

如果蓝牙代理不适合您的使用场景，请考虑在使用本地适配器时使用 Home Assistant 操作系统，因为它包含了解决其他操作系统中未解决的问题的蓝牙补丁。

配置

虽然此集成是 default_config: 的一部分，以启用蓝牙适配器的自动发现，但只有通过设置配置流或手动将其添加到您的 configuration.yamlconfiguration.yaml 文件是 Home Assistant 的主要配置文件。它列出了要加载的集成及其特定配置。在某些情况下，需要直接在 configuration.yaml 文件中手动编辑配置。大多数集成可以在 UI 中配置。 [Learn more] 文件中，才能启用它。 在更改了configuration.yamlconfiguration.yaml 文件是 Home Assistant 的主要配置文件。它列出了要加载的集成及其特定配置。在某些情况下，需要直接在 configuration.yaml 文件中手动编辑配置。大多数集成可以在 UI 中配置。 [Learn more] 文件后，重启 Home Assistant 以应用更改。 该集成现在显示在集成页面的 设置 > 设备与服务 下。其实体在集成卡片上以及实体标签上列出。

# 示例 configuration.yaml 入口
bluetooth:

Linux 系统的要求

在 Linux 系统上，蓝牙要正常工作：

  • D-Bus 套接字必须对 Home Assistant 可访问。
  • 蓝牙适配器必须对 D-Bus 可访问并运行 BlueZ >= 5.43。强烈建议使用 BlueZ >= 5.63，因为较旧版本的蓝牙已被报告为不可靠。
  • D-Bus 实现应该是 dbus-broker。
  • 主机系统应运行 Linux 内核 5.15.62 或更高版本。

安装方法的额外要求

  • Home Assistant 操作系统：升级到 Home Assistant OS 9.0 或更高版本。
  • Home Assistant 容器：主机系统必须运行 BlueZ，并且 D-Bus 套接字必须可供 Home Assistant 在 容器内访问。
  • Home Assistant 监督：主机系统必须运行 BlueZ，并且 D-Bus 套接字必须可供 Home Assistant 在 容器内访问。
  • Home Assistant 核心：系统必须运行 BlueZ，并且 D-Bus 套接字必须可供 Home Assistant 访问。

容器、核心和监督安装的附加细节

在 Docker 容器中使 DBus 套接字可用

对于大多数系统，D-Bus 套接字位于 /run/dbus。该套接字必须在容器中可用，以使 Home Assistant 能够连接到 D-Bus 并访问蓝牙适配器。当使用 docker run 启动时，可以通过在命令中添加 -v /run/dbus:/run/dbus:ro 来实现。如果主机系统上的 D-Bus 套接字位于 /var/run/dbus，请改用 -v /var/run/dbus:/run/dbus:ro。

如果您使用 Docker Compose，请在 volumes 部分添加如下内容（根据需要进行调整）：

volumes:
  - /run/dbus:/run/dbus:ro
从 dbus-daemon 切换到 dbus-broker

按照 说明 切换到 dbus-broker。

安装 BlueZ

在基于 Debian 的主机系统上，可以使用 sudo apt-get -y install bluez 命令安装 BlueZ。

安装 USB 蓝牙适配器

某些系统可能不附带蓝牙，并需要 USB 适配器。首次安装适配器可能需要多次重启才能完全识别设备。

如果您遇到不可靠的蓝牙连接，安装一个短的 USB 延长线在蓝牙适配器和 Home Assistant 服务器之间可能会提高可靠性。

对于开发和测试，此蓝牙集成的开发人员主要使用 Feasycom FSC-BP119 (CSR8510A10) 📶。

知名兼容的高性能适配器

基于 Cambridge Silicon Radio (CSR) 的适配器

  • ANNE PRO CSR 4.0 (CSR8510A10)
  • Avantree BTDG-40S (CSR8510A10)
  • DIGITUS DN-30210-1 (CSR8510A10)
  • Enbiawit BT403 (CSR8510A10)
  • Feasycom FSC-BP119 (CSR8510A10) 📶
  • Gold Touch E-USB-BT4 (CSR8510A10)
  • HIDEEZ BT0015-01 (CSR8510A10)
  • Maxesla CSR 4.0 (CSR8510A10)
  • Nuu You BT40 (CSR8510A10)
  • ORICO BTA-403 (CSR8510A10)
  • ORICO BTA-409 (CSR8510A10)
  • Panda Wireless PBU40 (CSR8510A10)
  • PlanexCOMM BT-Micro4 (CSR8510A10)
  • QGOO BT-06A (CSR8510A10)
  • ROCKETEK BT4Y (CSR8510A10)
  • SABRENT BT-UB40 (CSR8510A10)
  • Sena UD100-G03 (CSR8510A10) 📶
  • StarTech USBBT1EDR4 (CSR8510A10)
  • Techkey PBT06H (CSR8510A10)
  • TRENDnet TBW-106UB (CSR8510A10)
  • TRENDnet TBW-107UB (CSR8510A10)
  • UGREEN CM109 (CSR8510A10)
  • Warmstor WBT-AD01 (CSR8510A10)
  • WAVLINK WL-BT4001 (CSR8510A10)

📶 表示外置天线

这些适配器中的大多数可以同时保持五（5）个连接。

这些适配器通常提供最快的连接时间，并且不需要额外的驱动程序或补丁文件。

基于 Broadcom (BCM) 的适配器

Warning

这些适配器可能需要额外的补丁文件，以便在 https://github.com/winterheart/broadcom-bt-firmware 上获得稳定操作。

目前没有支持的方法来在使用 Home Assistant 操作系统时安装这些补丁文件。

基于 Broadcom (BCM) 的适配器
  • ASUS USB-BT400 (BCM20702A0)
  • Cable Matters 604002-BLK (BCM20702A0)
  • GMYLE 3340 (BCM20702A0)
  • IOGEAR GBU521W6 (BCM20702A0)
  • INSIGNIA NS-PCY5BMA (BCM20702A0)
  • Kinivo BTD-400 (BCM20702A0)
  • LM Technologies LM506 (BCM20702A1)
  • LM Technologies LM1010 (BCM20702A0) 📶
  • Plugable USB-BT4LE (BCM20702A0)
  • SoundBot SB342 (BCM20702A0)
  • StarTech USBBT2EDR4 (BCM20702A0)
  • Targus ACB10US1 (BCM20702A0)

📶 表示外置天线

这些适配器中的大多数可以同时保持七 (7) 个连接。

基于 Cypress 的适配器

  • Raspberry Pi 3B+ (CYW43455)
  • Raspberry Pi 4B (CYW43455)

这些适配器通过 UART 总线连接，这可能限制它们的性能。

高性能标定方法

性能主要由适配器的芯片和 Linux 驱动的组合决定。一些使用相同芯片的厂商的性能不可接受，因此被列为不支持。

要将适配器标记为高性能，必须满足以下要求：

  • 在约 1 秒或更短的时间内建立连接
  • 每秒处理至少一个来自设备的广告而不丢失数据
  • 95% 的连接尝试在两次尝试内成功
  • 在 Home Assistant Core 2022.11.1 或更高版本和 Home Assistant 操作系统 9.3 或更高版本中满足上述要求
  • 必须能够同时保持五（5）个连接

性能测试使用以下硬件：

  • 在 GATT 服务被 BlueZ 缓存后与 Nanoleaf A19 灯泡 NL45-0800 建立活跃连接
  • 来自 Oral-B iO 系列8 的广告
  • 仅外部适配器：运行 Home Assistant 操作系统 9.3 的 Home Assistant Blue，配有 USB 延长线。

知名兼容适配器

Note

知名兼容适配器列表中包含那些未达到高性能要求但通常会正常工作的适配器。这些适配器的性能差异很大，可能需要长达三十秒或更长的时间才能建立连接。这些适配器也可能会错过广告，例如按钮按压或温度更新。

基于 Realtek RTL8761BU 的适配器

Warning

这些适配器没有复位引脚。当它们停止响应时，目前没有方法可以让内核自动重置它们，可能需要物理拔掉并重新插入以恢复操作。

基于 Realtek RTL8761BU 的适配器
  • ASUS USB-BT500 (RTL8761BU)
  • Avantree DG45 (RTL8761BU)
  • COMCAST CF-B03 (RTL8761BU)
  • COMCAST CF-B05 (RTL8761BU) 📶
  • EDUP LOVE EP-B3536 (RTL8761BU) 📶
  • ISEKIE KW-B3519 (RTL8761BU)
  • Maxuni BT-501 (RTL8761BU)
  • MPOW BH45A (RTL8761BU)
  • Plugable USB-BT5 (RTL8761BU)
  • StarTech USBA-BLUETOOTH-V5-C2 (RTL8761BU)
  • SUMEE BT501 (RTL8761BU)
  • UGREEN CM390 (RTL8761BU)
  • XDO BT802 (RTL8761BU) 📶
  • ZEXMTE BT-505 (RTL8761BU) 📶
  • ZEXMTE BT-DG54 (RTL8761BU) 📶
  • ZEXMTE Z01 (RTL8761BU) 📶
  • ZETSAGE BH451A (RTL8761BU) 📶

📶 表示外置天线

不支持的适配器

不支持的适配器
  • Alfa AWUS036EACS (RTL8821CU) - 频繁连接失败和断线
  • BASEUS BR8651A01 BA04 - 广告掉线
  • Belkin F8T003 ver 2. - 设置和成功添加失败
  • Bluegiga BLED112 - USB ID 2458:0001 还没有可用的驱动程序
  • EDIMAX EW-7611ULB (RTL8723BU) - 频繁连接失败和断线
  • EDUP EP-AC1661 (RTL8821CU) - 频繁连接失败和断线
  • eppfun AK3040G (ATS2851) - USB ID 10d7:b012 还没有可用的驱动程序
  • eppfun AK3040A (ATS2851) - USB ID 10d7:b012 还没有可用的驱动程序
  • KOAMTAC KBD 401G (CSR8510A10) - 适配器不稳定而掉线
  • TRIPP-LITE CU885A/U261-001-BT4 (CSR8510A10) - 适配器不稳定而掉线
  • QUMOX Bluetooth 5.0 (Barrot 8041A02) - 没有可用的驱动程序
  • UGREEEN CM591 (ATS2851) - USB ID 10d7:b012 还没有可用的驱动程序
  • UGREEEN CM749 (Barrot 芯片组) 📶 - USB ID 33fa:0010 还没有可用的驱动程序
  • tp-link UB400 (CSR4) - 频繁连接失败与活跃连接
  • tp-link UB500 (RTL8761BU) - 频繁连接失败与活跃连接
  • CSR 4.0 克隆，USB ID 0a12:0001 - 无法恢复的驱动程序故障：这些克隆通常在插入时会在系统日志中显示类似 CSR: Unbranded CSR clone detected; adding workarounds and force-suspending once... 的信息。
    • 多个未标记的适配器标有 CSR 4.0
    • 5 CORE CSR 4.0

📶 表示外置天线

多个适配器

蓝牙集成采用自动故障转移和连接路径逻辑来实现高可用性。

仅在 Linux 系统上支持多个本地蓝牙适配器。将适配器放置得足够远以减少干扰。

已知可以添加多个适配器的方法如下：

已遵循 库作者最佳实践 的集成将自动通过最佳信号的适配器进行连接，如果某个适配器变得不可用，则会转移到另一个活跃适配器。

被动扫描

如果主机系统运行 BlueZ 5.63 或更高版本并启用实验特性，则可以在每个适配器的选项流中启用被动扫描。此功能在 Home Assistant 操作系统 9.4 及更高版本中可用。

许多集成需要主动扫描，并且在被动扫描时可能无法正常工作。

选项

蓝牙 的选项可以通过用户界面设置，具体步骤如下：

  • 浏览到您的 Home Assistant 实例。
  • 转到 设置 > 设备与服务。
  • 如果配置了多个 蓝牙 实例，请选择您想配置的实例。
  • 选择集成，然后选择 配置。

远程适配器（蓝牙代理）

蓝牙集成支持接收来自外部适配器的广告数据，适用于不需要主动连接的设备和传感器，同时也支持建立主动连接。远程扫描仪的数量仅受主机系统性能的限制。

在添加多个远程适配器以增加范围或可用连接插槽时，将它们分开以避免相互干扰。

以下远程适配器受到支持：

  • ESPHome
    • 蓝牙广告监听：ESPHome ESP32 设备，固件 2022.8.2 或更高版本
    • 蓝牙广告捆绑：ESPHome ESP32 设备，固件 2023.6.0 或更高版本
    • 单个活跃连接：ESPHome ESP32 设备，固件 2022.9.3 或更高版本
    • 多个活跃连接：ESPHome ESP32 设备，固件 2022.11.0 或更高版本
  • Shelly
    • 蓝牙广告监听：Shelly Gen2+ 设备
    • 蓝牙广告捆绑：Shelly Gen2+ 设备
    • 单个活跃连接：不支持
    • 多个活跃连接：不支持

蓝牙广告捆绑减少了 Home Assistant 与代理之间的流量，从而显著提高了性能，并减少了蓝牙和 WiFi 争夺媒体时间的时间，适用于共享无线电的设备。

故障排除

改善连接时间

连接时间和性能因蓝牙适配器和干扰而异。

Warning

在切换到更高性能的适配器时，请禁用旧的、性能较差的适配器。建立连接时考虑到最佳信号和可用连接插槽，性能将受到最差性能适配器的限制，因此才能到达远程设备。

以下适配器按性能从最佳到最差列出：

需要独占使用蓝牙适配器的集成

虽然较新的集成可以共享蓝牙适配器，但某些遗留集成需要独占使用适配器。启用此集成可能会阻止未更新以使用更新方法的集成正常工作。

删除此集成的配置条目将释放适配器的控制权，并允许其他集成获得蓝牙适配器的独占使用。如果您手动将 bluetooth: 添加到您的 configuration.yamlconfiguration.yaml 文件是 Home Assistant 的主要配置文件。它列出了要加载的集成及其特定配置。在某些情况下，需要直接在 configuration.yaml 文件中手动编辑配置。大多数集成可以在 UI 中配置。 [Learn more]，您也必须将其删除，以防止配置被重新创建。如果您需要继续使用遗留集成，请考虑在 Linux 系统上添加第二个蓝牙适配器，因为未来更多集成将使用蓝牙集成。

蓝牙干扰其他设备

无线电的干扰源可能导致传输/接收丢失或连接问题，并表现出发送和接收蓝牙消息时的错误/失败，这可能会显著降低性能。以下是一些基本但重要的提示，可帮助您找到良好的设置起点，以实现更好的信号质量、覆盖率和更远的范围。

遵循以下所有优化提示应该会显著改善您的蓝牙无线电适配器的接收。以下见解描述了如何应对低功耗 2.4 GHz 数字无线电的已知限制。这可以解决或避免许多由干扰或蓝牙无线电适配器或设备位置不当引起的已知问题。

计算机、外设和设备会产生 电磁干扰（也称为 EMI/EMI/RMI），这可能会干扰 2.4 GHz 无线电波段频率上的信号传输，从而降低与蓝牙适配器/设备的无线通信。

例如，未屏蔽的 USB 3 端口及其电缆尤其臭名昭著地影响 2.4 GHz 无线电接收。尽量将蓝牙适配器放置在尽可能远离任何潜在 EMI/EMI/RMI 源的地方，可以使用一条足够长的、适当屏蔽的 USB 延长线。

有助于改善大多数蓝牙设置的简单操作和常见干扰根源

  • 蓝牙适配器硬件：
    • 旧/过时的蓝牙适配器硬件或蓝牙适配器天线性能差：
      • 购买并使用基于更新/现代芯片硬件的支持蓝牙 USB 适配器。
        • 考虑使用带有外部天线的蓝牙适配器。
        • 虽然较旧的适配器可能可行，但它们可能存在过时的硬件或旧固件，导致操作不可靠。
    • 蓝牙适配器上的固件差或过时：
      • 更新蓝牙适配器上的最新蓝牙芯片固件。如果制造商或芯片制造商提供固件，更新通常比较简单。
  • 蓝牙适配器对 RFI 敏感，可能对各种 EMI/EMF 干扰非常敏感：
    • 蓝牙适配器放置不当或蓝牙适配器天线方向错误：
      • 使用长 USB 延长线将蓝牙适配器放在远离干扰和障碍物的地方。
        • 确保 USB 延长线适当屏蔽（较厚的电缆通常具有这种特性）。
          • USB 延长线可以更方便地调整蓝牙适配器/天线的方向。
      • 尝试不同的物理位置和蓝牙适配器或其天线的方向：
        • 蓝牙适配器的最佳位置尽可能接近房子的中间。
        • 尝试将蓝牙适配器放置在远离墙壁、天花板和地板的地方。
        • 尝试蓝牙适配器外部天线（或整个蓝牙适配器）的不同方向。
    • 已知的 USB 3.0 端口/计算机/外设是 RFI/EMI/EMF 干扰的罪魁祸首。（参见参考文献 1 和 2）。
      • 确保只将蓝牙 USB 适配器连接到 USB 2.0 端口（而不是 USB 3.x 端口）。
        • 如果计算机只有 USB 3.x 端口，则通过有源 USB 2.0 集线器连接适配器：
          • USB 2.0 集线器将 USB 3.0 转换为 USB 2.0 端口，并避免 USB 3.0 造成的 EMF。
            • 使用外部电源的 USB 2.0 集线器将确保电源需求得到满足。
      • 通过添加全金属外壳/机箱/外壳来屏蔽任何未屏蔽的计算机/外设/设备。
        • 单板计算机和 USB 3.x 硬盘尤其被认为是 EMF/EMI/RFI 的来源。
          • 请注意，金属外壳可能会降低内部/内置蓝牙适配器的性能。
        • 另外，也请确保为任何此类外设/设备使用适当屏蔽的 USB 电缆。
    • Wi-Fi 路由器和 Wi-Fi 访问点或其他设备产生的 2.4 GHz RF 干扰 (RFI)：
      • 虽然蓝牙设计为与 Wi-Fi 共存，但其较强的信号可能会干扰。
        • 为保险起见，尽量将蓝牙适配器放在远离 Wi-Fi 访问点的地方。
      • 将蓝牙适配器放置在远离电气/电源电线/电缆、电源和家用电器的地方。

相关主题

相关链接