[esp32_ble] Add use_psram option to offload BT memory allocation to SPIRAM (#15644)

esphome/components/esp32_ble/__init__.py

@@ -7,6 +7,7 @@ from typing import Any
 
 from esphome import automation
 import esphome.codegen as cg
+from esphome.components.const import CONF_USE_PSRAM
 from esphome.components.esp32 import add_idf_sdkconfig_option, const, get_esp32_variant
 from esphome.components.esp32.const import VARIANT_ESP32C2
 import esphome.config_validation as cv
@@ -342,6 +343,9 @@ CONFIG_SCHEMA = cv.Schema(
         cv.Optional(CONF_MAX_CONNECTIONS, default=DEFAULT_MAX_CONNECTIONS): cv.All(
             cv.positive_int, cv.Range(min=1, max=IDF_MAX_CONNECTIONS)
         ),
+        cv.Optional(CONF_USE_PSRAM): cv.All(
+            cv.only_on_esp32, cv.requires_component("psram"), cv.boolean
+        ),
     }
 ).extend(cv.COMPONENT_SCHEMA)
 
@@ -598,6 +602,22 @@ async def to_code(config):
     add_idf_sdkconfig_option("CONFIG_BT_ENABLED", True)
     add_idf_sdkconfig_option("CONFIG_BT_BLE_42_FEATURES_SUPPORTED", True)
 
+    # When PSRAM and BT are used together, Bluedroid should prefer SPIRAM for
+    # heap allocations and use dynamic (heap-based) environment memory tables
+    # instead of large static DRAM arrays. This frees ~40 kB of internal RAM.
+    # Reference: Espressif ADF Design Considerations
+    # https://espressif-docs.readthedocs-hosted.com/projects/esp-adf/en/latest/
+    #            design-guide/design-considerations.html
+    if config.get(CONF_USE_PSRAM, False):
+        cg.add_define("USE_ESP32_BLE_PSRAM")
+        # CONFIG_BT_ALLOCATION_FROM_SPIRAM_FIRST is only available on ESP32
+        # (BTDM dual-mode controller). BLE-only SoCs (C3, S3, C2, H2) do not
+        # expose this Kconfig symbol; applying it there would cause a build error.
+        if get_esp32_variant() == const.VARIANT_ESP32:
+            add_idf_sdkconfig_option("CONFIG_BT_ALLOCATION_FROM_SPIRAM_FIRST", True)
+        # CONFIG_BT_BLE_DYNAMIC_ENV_MEMORY applies to all Bluedroid-enabled variants.
+        add_idf_sdkconfig_option("CONFIG_BT_BLE_DYNAMIC_ENV_MEMORY", True)
+
     # Register the core BLE loggers that are always needed
     register_bt_logger(BTLoggers.GAP, BTLoggers.BTM, BTLoggers.HCI)
 

esphome/components/esp32_ble/ble.cpp

@@ -667,6 +667,9 @@ void ESP32BLE::dump_config() {
                   "  MAC address: %s\n"
                   "  IO Capability: %s",
                   mac_s, io_capability_s);
+#ifdef USE_ESP32_BLE_PSRAM
+    ESP_LOGCONFIG(TAG, "  PSRAM BLE allocation: enabled");
+#endif
 
 #ifdef ESPHOME_ESP32_BLE_EXTENDED_AUTH_PARAMS
     const char *auth_req_mode_s = "<default>";

esphome/core/defines.h

@@ -48,6 +48,7 @@
 #define USE_ENTITY_DEVICE_CLASS
 #define USE_ENTITY_ICON
 #define USE_ENTITY_UNIT_OF_MEASUREMENT
+#define USE_ESP32_BLE_PSRAM
 #define USE_ESP32_CAMERA_JPEG_CONVERSION
 #define USE_ESP32_HOSTED
 #define USE_ESP32_IMPROV_STATE_CALLBACK

tests/components/esp32_ble/common_use_psram.yaml

@@ -0,0 +1,4 @@
+esp32_ble:
+  use_psram: true
+
+psram:

tests/components/esp32_ble/test.esp32-ard.yaml

@@ -1 +1,2 @@
 <<: !include common.yaml
+<<: !include common_use_psram.yaml

tests/components/esp32_ble/test.esp32-idf.yaml

@@ -1,4 +1,5 @@
 <<: !include common.yaml
+<<: !include common_use_psram.yaml
 
 esp32_ble:
   io_capability: keyboard_only

tests/components/esp32_ble/test.esp32-p4-idf.yaml

@@ -2,6 +2,7 @@ packages:
   ble: !include ../../test_build_components/common/ble/esp32-p4-idf.yaml
 
 <<: !include common.yaml
+<<: !include common_use_psram.yaml
 
 esp32_ble:
   io_capability: keyboard_only