跳转到内容
ESPHome - 智能家居，简单易用

BLE 组件

ESPHome 中的 esp32_ble 组件在设备上设置蓝牙 LE 协议栈，以便 Esp32 Ble Server 可以运行。

WARNING

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

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

# 示例配置


esp32_ble:
  io_capability: keyboard_only
  disable_bt_logs: true  # 默认值，节省 flash
  connection_timeout: 20s  # 默认值，与客户端超时匹配
  max_connections: 3  # 默认值，BLE 总连接数
  # advertising: true  # 仅在高级用例中需要
  max_notifications: 12  # 默认值，如需要可增加

配置变量

Section titled “配置变量”

  • io_capability (可选, enum): 此 ESP32 的 IO 能力，用于与其他 BLE 设备安全连接。默认为 none。

    • none - 无 IO 能力（需要 PIN 码认证的连接将失败）
    • keyboard_only - 仅有键盘输入 PIN 码（或固定的 PIN 码）
    • display_only - 仅有显示屏显示 PIN 码
    • keyboard_display - 有键盘和显示屏
    • display_yes_no - 有显示屏显示 PIN 码和按钮确认或拒绝连接

  • enable_on_boot (可选, boolean): 如果启用，BLE 接口将在启动时启用。默认为 true。

  • name (可选, string): BLE 设备的名称。

  • disable_bt_logs (可选, boolean): 启用时，禁用配置组件未使用的蓝牙日志类别。这通过仅包含配置所需的记录器来节省 flash 存储器。默认为 true。

NOTE

disable_bt_logs 选项智能地仅禁用配置不需要的蓝牙日志类别。每个蓝牙组件注册其所需的特定记录器，所有未使用的记录器在编译期间自动禁用。这包括 ESPHome 的 BLE 实现未使用的经典蓝牙功能（如 RFCOMM、A2DP、HID）的记录器。

  • connection_timeout (可选, 时间): 等待 BLE 连接建立的最长时间。默认为 20s。

    • 范围：10 到 180 秒
    • 此超时应与您的 BLE 客户端软件使用的超时一致，以防止连接槽浪费

NOTE

当将 ESPHome 用作蓝牙代理时，connection_timeout 选项特别重要。默认的 20 秒与 aioesphomeapi 和 bleak-retry-connector 使用的超时相匹配。如果连接尝试在客户端超时，但 ESP-IDF 继续尝试连接，则连接槽仍然被占用且无法用于新连接。将此设置为与您的客户端超时匹配可确保在连接失败时立即释放连接槽。

  • advertising (可选, boolean): 手动启用 BLE 广播支持。当使用 Esp32 Ble Server 或 Esp32 Ble Beacon 时会自动启用。仅当您需要广播功能但不使用这些组件时才将其设置为 true。默认为 false。

NOTE

advertising 选项是一项高级功能，可手动启用 BLE 广播编译。在大多数情况下，您不需要设置此选项，因为当使用需要它的组件（如 esp32_ble_server 或 esp32_ble_beacon）时会自动启用广播。此选项主要用于自定义组件或特殊用例，当您需要广播功能但不需要标准服务器或信标组件时。

  • advertising_cycle_time (可选, 时间): 循环多个广播的时间间隔。仅当启用广播时适用。默认为 10s。

  • max_connections (可选, integer): 同时 BLE 连接的最大数量（客户端 + 服务器合计）。默认为 3。

    • 范围：1 到 9
    • 每个连接槽大约消耗 1KB RAM
    • 此限制在 Esp32 Ble Tracker（BLE 客户端）、蓝牙代理 和 Esp32 Ble Server（BLE 服务器）之间共享
    • ESP32-C3/S3 上 BLE 实例总数（ADV/SCAN + 连接）限制为 10
    • 建议不要超过 5 个连接槽以避免内存问题

NOTE

max_connections 选项在 ESP-IDF 中设置 CONFIG_BT_ACL_CONNECTIONS（包括 ADV/SCAN 的总实例）和 CONFIG_BTDM_CTRL_BLE_MAX_CONN（仅连接槽）。此配置之前位于 esp32_ble_tracker 中，但已移至此处，因为它适用于所有 BLE 功能（客户端和服务器）。为了向后兼容，在 esp32_ble_tracker 中设置它仍然可以工作，但会显示弃用警告。

  • max_notifications (可选, integer): 所有连接中可以启用通知的 BLE 特征的最大数量。默认为 12。

    • 范围：1 到 64
    • 这是所有 BLE 连接共享的全局限制
    • 如果在启用通知时看到 ESP_GATT_NO_RESOURCES（status=128）错误，请增加此值

NOTE

max_notifications 选项控制 CONFIG_BT_GATTC_NOTIF_REG_MAX ESP-IDF 设置。此限制是每个 GATT 客户端接口，而不是每个连接。如果您将 ESPHome 用作蓝牙代理，且有多个设备具有许多需要通知的特征，您可能需要增加此值。日志中的 status=128 错误表示您已达到此限制。

ble.disable 动作

Section titled “ble.disable 动作”

此动作按需关闭 BLE 接口。

on_...:
  then:
    - ble.disable:

NOTE

如果您不希望 BLE 在启动时启用，可以将配置选项 enable_on_boot 设置为 false。

ble.enable 动作

Section titled “ble.enable 动作”

此动作按需开启 BLE 接口。

on_...:
  then:
    - ble.enable:

NOTE

如果您不希望 BLE 在启动时启用，可以将配置选项 enable_on_boot 设置为 false。

ble.enabled 条件

Section titled “ble.enabled 条件”

此条件检查 BLE 当前是否已启用。

on_...:
  - if:
      condition: ble.enabled
      then:
        - ble.disable:
      else:
        - ble.enable:

此条件的 lambda 等效写法是 id(ble_id).is_active()。

另请参阅

Section titled “另请参阅”