跳转到内容
ESPHome - 让智能家居更简单2026.7.0

BLE 组件

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

WARNING

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

如果在设备的 配置中加入了过多的组件，很可能会发生崩溃。语音助手等 消耗大量内存的组件和其它音频组件最可能导致问题。

# Example configuration


esp32_ble:
  io_capability: keyboard_only
  disable_bt_logs: true  # Default, saves flash
  connection_timeout: 20s  # Default, matches client timeout
  max_connections: 3  # Default, total BLE connections
  # advertising: true  # Only needed for advanced use cases
  max_notifications: 12  # Default, increase if needed
  # auth_req_mode: sc_mitm_bond  # Optional, for advanced security
  # max_key_size: 16  # Optional, encryption key size (7-16)
  # min_key_size: 7   # Optional, encryption key size (7-16)

配置变量

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)：启用时，禁用配置组件未使用的蓝牙日志分类。这通过仅包含配置所需的日志器来节省闪存。默认为 true。

NOTE

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

  • connection_timeout (可选, Time)：等待建立 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 (可选, Time)：在多个广播之间循环切换的时间间隔。仅在启用广播时适用。默认为 10s。

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

    • 范围：1 至 9
    • 每个连接槽位大约消耗 1KB 的 RAM
    • 此限制在 Esp32 Ble Tracker（BLE 客户端）、Bluetooth Proxy 和 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 表示已达到此限制。

  • max_key_size (可选, integer)：支持的最大加密密钥大小。必须在 7 和 16 之间。除非设备需要特殊处理，否则不指定则使用 ESP32 默认值。

  • min_key_size (可选, integer)：从对端要求的最小加密密钥大小。必须在 7 和 16 之间。除非设备需要特殊处理，否则不指定则使用 ESP32 默认值。

  • auth_req_mode (可选, enum)：认证请求模式。默认为 ESP-IDF 默认值。除非设备需要特殊处理，否则不指定。

    • no_bond - 无绑定
    • bond - 绑定
    • mitm - 仅 MITM
    • bond_mitm - 带 MITM 的绑定
    • sc_only - 仅安全连接
    • sc_bond - 带绑定的安全连接
    • sc_mitm - 带 MITM 的安全连接
    • sc_mitm_bond - 带 MITM 和绑定的安全连接

    有关这些模式的详细信息，请参阅ESP32 SDK 文档。

  • use_psram (可选, boolean)：请求蓝牙协议栈从 PSRAM 而不是内部 RAM 分配其内存缓冲区，为其他用途释放约 40 kB。默认为 false。需要配置 PSRAM。

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 “另请参阅”