ESP32 蓝牙低功耗跟踪器集线器

esp32_ble_tracker 组件会创建一个全局集线器，以便你可以使用你的 ESP32 节点来跟踪低功耗蓝牙设备。

参见设备设置了解如何确定设备的 MAC 地址并使用 ESPHome 进行跟踪。

WARNING

ESP32 上的 BLE 软件栈会占用设备上大量的 RAM。

如果你在设备的配置中包含太多额外组件，很可能出现崩溃。内存密集型组件，如语音助手和其他音频组件，最有可能引发问题。

# Example configuration entry
esp32_ble_tracker:

binary_sensor:
  - platform: ble_presence
    mac_address: XX:XX:XX:XX:XX:XX
    name: "ESP32 BLE Presence Google Home Mini"

sensor:
  - platform: ble_rssi
    mac_address: XX:XX:XX:XX:XX:XX
    name: "BLE Google Home Mini RSSI value"
  - platform: xiaomi_hhccjcy01
    mac_address: XX:XX:XX:XX:XX:XX
    temperature:
      name: "Xiaomi MiFlora Temperature"
    moisture:
      name: "Xiaomi MiFlora Moisture"
    illuminance:
      name: "Xiaomi MiFlora Illuminance"
    conductivity:
      name: "Xiaomi MiFlora Soil Conductivity"
    battery_level:
      name: "Xiaomi MiFlora Battery Level"
  - platform: xiaomi_lywsdcgq
    mac_address: XX:XX:XX:XX:XX:XX
    temperature:
      name: "Xiaomi MiJia Temperature"
    humidity:
      name: "Xiaomi MiJia Humidity"
    battery_level:
      name: "Xiaomi MiJia Battery Level"

NOTE

为 ESP32 首次启用此组件时，需要调整代码分区大小。请在向配置中添加此组件时通过 USB 刷写 ESP32。之后，你就可以再次使用 OTA 更新了。

配置变量

• scan_parameters (Optional): 用于配置 ESP32 扫描行为的高级参数。 有关参考，另请参阅德州仪器（Texas Instruments）的这篇指南。

  • interval (Optional, Time): 每个连续扫描窗口之间的时间间隔。 这是 ESP 在每个 BLE 广播信道上所花费的时间。 默认为 320ms。

  • window (Optional, Time): 在每个扫描间隔内，ESP 主动监听信道上的数据包的时间。如果该值接近 interval 值，ESP 将 花费更长的时间来监听数据包（但也会消耗更多电量）。默认为 30ms

  • duration (Optional, Time): 每次完整扫描的持续时间。这对设备没有实际 影响，但可用于调试 BLE 协议栈。默认为 5min。

  • active (Optional, boolean): 是否在收到广播数据包后主动发送扫描请求以请求更多数据。 对于某些设备，这是接收所有数据的必要条件， 但也会更多地消耗这些设备的电量。有些设备不需要这样做，在这种情况下 你可以通过将其设置为 false 来节省电量并减少射频污染。默认为 true。

  • continuous (Optional, boolean): 是否持续扫描（一直）或仅在被要求开始扫描时（通过 start_scan 操作）才扫描。默认为 true。

• software_coexistence (Optional, boolean): 启用后，软件共存机制将在 BLE 连接初期 短暂地优先处理蓝牙而非 Wi-Fi， 这可以提高可靠性。仅在配置了 wifi 组件时可用。 默认为 true。

• id (Optional, ID): 手动指定此 ESP32 BLE 集线器的 ID。

• max_connections (Optional, int): 已弃用 - 此选项已移至 Esp32 Ble 组件。 请在该组件中配置 max_connections。此选项仅为向后兼容而保留。此选项将在 ESPHome 2026.10.0 中移除。

自动化：

• on_ble_advertise (Optional, Automation): 在收到蓝牙广播时执行的自动化。参见 on_ble_advertise 触发器。

• on_ble_manufacturer_data_advertise (Optional, Automation): 在收到带有制造商数据的蓝牙广播时执行的自动化。参见 on_ble_manufacturer_data_advertise 触发器。

• on_ble_service_data_advertise (Optional, Automation): 在收到带有服务数据的蓝牙广播时执行的自动化。参见 on_ble_service_data_advertise 触发器。

• on_scan_end (Optional, Automation): 在 BLE 扫描完成时执行的自动化（扫描的持续时间）。这在 continuous 设置为 true 或 false 时均有效。

ESP32 蓝牙低功耗跟踪器自动化

on_ble_advertise 触发器

当收到蓝牙广播时，将触发此自动化。一个类型为 API 参考：esp32_ble_tracker::ESPBTDevice 的变量 x 会被传递给自动化，供在 lambda 中使用。

esp32_ble_tracker:
  on_ble_advertise:
    - mac_address:
        - XX:XX:XX:XX:XX:XX
        - XX:XX:XX:XX:XX:XX
      then:
        - lambda: |-
            ESP_LOGD("ble_adv", "New BLE device");
            ESP_LOGD("ble_adv", "  address: %s", x.address_str().c_str());
            ESP_LOGD("ble_adv", "  name: %s", x.get_name().c_str());
            ESP_LOGD("ble_adv", "  Advertised service UUIDs:");
            for (auto uuid : x.get_service_uuids()) {
                ESP_LOGD("ble_adv", "    - %s", uuid.to_string().c_str());
            }
            ESP_LOGD("ble_adv", "  Advertised service data:");
            for (auto data : x.get_service_datas()) {
                ESP_LOGD("ble_adv", "    - %s: (length %i)", data.uuid.to_string().c_str(), data.data.size());
            }
            ESP_LOGD("ble_adv", "  Advertised manufacturer data:");
            for (auto data : x.get_manufacturer_datas()) {
                ESP_LOGD("ble_adv", "    - %s: (length %i)", data.uuid.to_string().c_str(), data.data.size());
            }

配置变量

• mac_address (Optional, list of MAC Address): 用于过滤此自动化的 MAC 地址。
• 参见自动化。

on_ble_manufacturer_data_advertise 触发器

当收到带有制造商数据的蓝牙广播时，将触发此自动化。一个 类型为 std::vector<uint8_t> 的变量 x 会被传递给自动化，供在 lambda 中使用。

sensor:
  - platform: template
    name: "BLE Sensor"
    id: ble_sensor

esp32_ble_tracker:
  on_ble_manufacturer_data_advertise:
    - mac_address: XX:XX:XX:XX:XX:XX
      manufacturer_id: 0590
      then:
        - lambda: |-
            if (x[0] != 0x7b || x[1] != 0x61) return;
            int value = x[2] + (x[3] << 8);
            id(ble_sensor).publish_state(value);

配置变量

• mac_address (Optional, MAC Address): 用于过滤此自动化的 MAC 地址。
• manufacturer_id (Required, string): 16 位、32 位或 128 位 BLE 制造商 ID。
• 参见自动化。

on_ble_service_data_advertise 触发器

当收到带有服务数据的蓝牙广播时，将触发此自动化。一个 类型为 std::vector<uint8_t> 的变量 x 会被传递给自动化，供在 lambda 中使用。

sensor:
  - platform: template
    name: "BLE Sensor"
    id: ble_sensor

esp32_ble_tracker:
  on_ble_service_data_advertise:
    - mac_address: XX:XX:XX:XX:XX:XX
      service_uuid: 181A
      then:
        - lambda: 'id(ble_sensor).publish_state(x[0]);'

配置变量

• mac_address (Optional, MAC Address): 用于过滤此自动化的 MAC 地址。
• service_uuid (Required, string): 16 位、32 位或 128 位 BLE 服务 UUID。
• 参见自动化。

on_scan_end 触发器

当蓝牙扫描序列完成时，将触发此自动化。如果使用 continuous 设置为 true 运行，则每次扫描完成时都会触发（即一次扫描的持续时间）。

esp32_ble_tracker:
  on_scan_end:
    - then:
        - lambda: |-
             ESP_LOGD("ble_auto", "The scan has ended!");

配置变量

• 无

• 参见自动化。

esp32_ble_tracker.start_scan 操作

启动一次蓝牙扫描。如果此时已有扫描正在进行，则该操作会被忽略。

esp32_ble_tracker:
  scan_parameters:
    continuous: false

on_...:
  - esp32_ble_tracker.start_scan:

配置变量

• continuous (Optional, boolean, templatable): 是否以连续模式启动扫描。默认为 false

NOTE

此操作也可以用 lambda 编写：

esp32_ble_tracker:
  id: ble_tracker_id

id(ble_tracker_id).start_scan()

esp32_ble_tracker.stop_scan 操作

停止蓝牙扫描。可以使用上面的 start scan 操作再次启动它。

esp32_ble_tracker:

on_...:
  - esp32_ble_tracker.stop_scan:

在单核芯片上使用

在双核设备上，WiFi 组件在核心 1 上运行，而此组件在核心 0 上运行。 在 ESP32-C3 等单核芯片上使用此组件时，WiFi 和 ble_tracker 都必须在 同一核心上运行，这已知会导致连接到 WiFi 时出现问题。解决方法是仅在 原生 API 连接时启用跟踪器。以下配置即可实现此目的：

esp32_ble_tracker:
  scan_parameters:
    continuous: false

api:
  encryption:
    key: !secret encryption_key
  on_client_connected:
    - esp32_ble_tracker.start_scan:
       continuous: true
  on_client_disconnected:
    - if:
        condition:
          not:
            api.connected:
        then:
          - esp32_ble_tracker.stop_scan:

另请参见

• ESP32 蓝牙低功耗扫描器
• ESP32 蓝牙低功耗 RSSI 传感器
• b-parasite
• 小米米家 BLE 传感器
• 小米体重秤传感器
• Inkbird IBS-TH1、IBS-TH1 Mini 和 IBS-TH2 BLE 传感器
• Mopeka Pro Check BLE 传感器
• RuuviTag 开源 BLE 传感器
• BLE 客户端
• 蓝牙代理
• ESP32 BLE for Arduino，作者：Neil Kolban。
• API 参考：esp32_ble_tracker.h