BLE Component

The esp32_ble component in ESPHome sets up the Bluetooth LE stack on the device so that a BLE Server can run.

Warning

The BLE software stack on the ESP32 consumes a significant amount of RAM on the device.

Crashes are likely to occur if you include too many additional components in your device’s configuration. Memory-intensive components such as Voice Assistant and other audio components are most likely to cause issues.

# Example configuration

esp32_ble:
  io_capability: keyboard_only
  disable_bt_logs: true  # Default, saves flash

Configuration variables:

  • io_capability (Optional, enum): The IO capability of this ESP32, used for securely connecting to other BLE devices. Defaults to none.

    • none - No IO capability (Connections that require PIN code authentication will fail)

    • keyboard_only - Only a keyboard to enter PIN codes (or a fixed PIN code)

    • display_only - Only a display to show PIN codes

    • keyboard_display - A keyboard and a display

    • display_yes_no - A display to show PIN codes and buttons to confirm or deny the connection

  • enable_on_boot (Optional, boolean): If enabled, the BLE interface will be enabled on boot. Defaults to true.

  • name (Optional, string): The name of the BLE device.

  • disable_bt_logs (Optional, boolean): When enabled, disables Bluetooth logging categories that are not used by the configured components. This saves flash memory by only including the loggers needed by your configuration. Defaults to true.

Note

The disable_bt_logs option intelligently disables only the Bluetooth logging categories that are not required by your configuration. Each Bluetooth component registers the specific loggers it needs, and all unused loggers are automatically disabled during compilation. This includes loggers for Classic Bluetooth features (like RFCOMM, A2DP, HID) that are not used by ESPHome’s BLE implementation.

ble.disable Action

This action turns off the BLE interface on demand.

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

Note

The configuration option enable_on_boot can be set to false if you do not want BLE to be enabled on boot.

ble.enable Action

This action turns on the BLE interface on demand.

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

Note

The configuration option enable_on_boot can be set to false if you do not want BLE to be enabled on boot.

ble.enabled Condition

This Condition checks if BLE is currently enabled or not.

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

The lambda equivalent for this is id(ble_id).is_active().

See Also