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

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

有关如何确定设备的 MAC 地址并使用 ESPHome 追踪它的信息，请参阅设置设备。

WARNING

ESP32 上的 BLE 软件协议栈会消耗设备上大量的 RAM。

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

# 示例配置条目
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 (可选): 用于配置 ESP32 扫描行为的高级参数。另请参阅德州仪器的本指南作为参考。

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

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

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

  • active (可选, boolean): 是否主动发送扫描请求以在收到广播数据包后请求更多数据。对于某些设备，这是接收所有数据所必需的，但也会稍微增加这些设备的功耗。某些设备不需要此功能，在这种情况下，您可以将其设置为 false 以节省电量并减少 RF 干扰。默认为 true。

  • continuous (可选, boolean): 是持续扫描（永远）还是仅在请求开始扫描时扫描（使用 start_scan 动作）。默认为 true。

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

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

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

自动化：

• on_ble_advertise (可选, 自动化): 当收到蓝牙广播时要执行的自动化。参见 on_ble_advertise 触发器。

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

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

• on_scan_end (可选, 自动化): 当 BLE 扫描完成（扫描持续时间结束）时要执行的自动化。这适用于 continuous 设置为 true 或 false 的情况。

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

on_ble_advertise 触发器

当收到蓝牙广播时，将触发此自动化。一个类型为 API Reference: 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 (可选, MAC 地址列表): 要为此自动化过滤的 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 (可选, MAC 地址): 要为此自动化过滤的 MAC 地址。
• manufacturer_id (必需, 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 (可选, MAC 地址): 要为此自动化过滤的 MAC 地址。
• service_uuid (必需, 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 (可选, boolean): 是否以连续模式开始扫描。默认为 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:
    - esp32_ble_tracker.stop_scan:

另请参阅

• ESP32 蓝牙低功耗扫描器
• ESP32 蓝牙低功耗 RSSI 传感器
• b-parasite
• 小米 Mijia BLE 传感器
• 小米 Miscale 传感器
• Inkbird IBS-TH1, IBS-TH1 Mini 和 IBS-TH2 BLE 传感器
• Mopeka Pro Check BLE 传感器
• RuuviTag 开源 BLE 传感器
• BLE 客户端
• 蓝牙代理
• ESP32 BLE for Arduino 作者 Neil Kolban。
• API Reference: esp32_ble_tracker.h