esphome 2025.7.5__py3-none-any.whl → 2025.8.0__py3-none-any.whl

esphome/components/esp32_ble_client/ble_client_base.cpp

@@ -5,10 +5,27 @@
 
 #ifdef USE_ESP32
 
-namespace esphome {
-namespace esp32_ble_client {
+#include <esp_gap_ble_api.h>
+#include <esp_gatt_defs.h>
+
+namespace esphome::esp32_ble_client {
 
 static const char *const TAG = "esp32_ble_client";
+
+// Intermediate connection parameters for standard operation
+// ESP-IDF defaults (12.5-15ms) are too slow for stable connections through WiFi-based BLE proxies,
+// causing disconnections. These medium parameters balance responsiveness with bandwidth usage.
+static const uint16_t MEDIUM_MIN_CONN_INTERVAL = 0x07;  // 7 * 1.25ms = 8.75ms
+static const uint16_t MEDIUM_MAX_CONN_INTERVAL = 0x09;  // 9 * 1.25ms = 11.25ms
+// The timeout value was increased from 6s to 8s to address stability issues observed
+// in certain BLE devices when operating through WiFi-based BLE proxies. The longer
+// timeout reduces the likelihood of disconnections during periods of high latency.
+static const uint16_t MEDIUM_CONN_TIMEOUT = 800;  // 800 * 10ms = 8s
+
+// Fastest connection parameters for devices with short discovery timeouts
+static const uint16_t FAST_MIN_CONN_INTERVAL = 0x06;  // 6 * 1.25ms = 7.5ms (BLE minimum)
+static const uint16_t FAST_MAX_CONN_INTERVAL = 0x06;  // 6 * 1.25ms = 7.5ms
+static const uint16_t FAST_CONN_TIMEOUT = 1000;       // 1000 * 10ms = 10s
 static const esp_bt_uuid_t NOTIFY_DESC_UUID = {
     .len = ESP_UUID_LEN_16,
     .uuid =
@@ -27,8 +44,10 @@ void BLEClientBase::set_state(espbt::ClientState st) {
   ESPBTClient::set_state(st);
 
   if (st == espbt::ClientState::READY_TO_CONNECT) {
-    // Enable loop when we need to connect
+    // Enable loop for state processing
     this->enable_loop();
+    // Connect immediately instead of waiting for next loop
+    this->connect();
   }
 }
 
@@ -45,11 +64,6 @@ void BLEClientBase::loop() {
     }
     this->set_state(espbt::ClientState::IDLE);
   }
-  // READY_TO_CONNECT means we have discovered the device
-  // and the scanner has been stopped by the tracker.
-  else if (this->state_ == espbt::ClientState::READY_TO_CONNECT) {
-    this->connect();
-  }
   // If its idle, we can disable the loop as set_state
   // will enable it again when we need to connect.
   else if (this->state_ == espbt::ClientState::IDLE) {
@@ -64,40 +78,7 @@ void BLEClientBase::dump_config() {
                 "  Address: %s\n"
                 "  Auto-Connect: %s",
                 this->address_str().c_str(), TRUEFALSE(this->auto_connect_));
-  std::string state_name;
-  switch (this->state()) {
-    case espbt::ClientState::INIT:
-      state_name = "INIT";
-      break;
-    case espbt::ClientState::DISCONNECTING:
-      state_name = "DISCONNECTING";
-      break;
-    case espbt::ClientState::IDLE:
-      state_name = "IDLE";
-      break;
-    case espbt::ClientState::SEARCHING:
-      state_name = "SEARCHING";
-      break;
-    case espbt::ClientState::DISCOVERED:
-      state_name = "DISCOVERED";
-      break;
-    case espbt::ClientState::READY_TO_CONNECT:
-      state_name = "READY_TO_CONNECT";
-      break;
-    case espbt::ClientState::CONNECTING:
-      state_name = "CONNECTING";
-      break;
-    case espbt::ClientState::CONNECTED:
-      state_name = "CONNECTED";
-      break;
-    case espbt::ClientState::ESTABLISHED:
-      state_name = "ESTABLISHED";
-      break;
-    default:
-      state_name = "UNKNOWN_STATE";
-      break;
-  }
-  ESP_LOGCONFIG(TAG, "  State: %s", state_name.c_str());
+  ESP_LOGCONFIG(TAG, "  State: %s", espbt::client_state_to_string(this->state()));
   if (this->status_ == ESP_GATT_NO_RESOURCES) {
     ESP_LOGE(TAG, "  Failed due to no resources. Try to reduce number of BLE clients in config.");
   } else if (this->status_ != ESP_GATT_OK) {
@@ -105,6 +86,7 @@ void BLEClientBase::dump_config() {
   }
 }
 
+#ifdef USE_ESP32_BLE_DEVICE
 bool BLEClientBase::parse_device(const espbt::ESPBTDevice &device) {
   if (!this->auto_connect_)
     return false;
@@ -122,15 +104,46 @@ bool BLEClientBase::parse_device(const espbt::ESPBTDevice &device) {
   this->remote_addr_type_ = device.get_address_type();
   return true;
 }
+#endif
 
 void BLEClientBase::connect() {
-  ESP_LOGI(TAG, "[%d] [%s] 0x%02x Attempting BLE connection", this->connection_index_, this->address_str_.c_str(),
+  ESP_LOGI(TAG, "[%d] [%s] 0x%02x Connecting", this->connection_index_, this->address_str_.c_str(),
            this->remote_addr_type_);
   this->paired_ = false;
+
+  // Set preferred connection parameters before connecting
+  // Use FAST for all V3 connections (better latency and reliability)
+  // Use MEDIUM for V1/legacy connections (balanced performance)
+  uint16_t min_interval, max_interval, timeout;
+  const char *param_type;
+
+  if (this->connection_type_ == espbt::ConnectionType::V3_WITHOUT_CACHE ||
+      this->connection_type_ == espbt::ConnectionType::V3_WITH_CACHE) {
+    min_interval = FAST_MIN_CONN_INTERVAL;
+    max_interval = FAST_MAX_CONN_INTERVAL;
+    timeout = FAST_CONN_TIMEOUT;
+    param_type = "fast";
+  } else {
+    min_interval = MEDIUM_MIN_CONN_INTERVAL;
+    max_interval = MEDIUM_MAX_CONN_INTERVAL;
+    timeout = MEDIUM_CONN_TIMEOUT;
+    param_type = "medium";
+  }
+
+  auto param_ret = esp_ble_gap_set_prefer_conn_params(this->remote_bda_, min_interval, max_interval,
+                                                      0,  // latency: 0
+                                                      timeout);
+  if (param_ret != ESP_OK) {
+    ESP_LOGW(TAG, "[%d] [%s] esp_ble_gap_set_prefer_conn_params failed: %d", this->connection_index_,
+             this->address_str_.c_str(), param_ret);
+  } else {
+    this->log_connection_params_(param_type);
+  }
+
+  // Now open the connection
   auto ret = esp_ble_gattc_open(this->gattc_if_, this->remote_bda_, this->remote_addr_type_, true);
   if (ret) {
-    ESP_LOGW(TAG, "[%d] [%s] esp_ble_gattc_open error, status=%d", this->connection_index_, this->address_str_.c_str(),
-             ret);
+    this->log_gattc_warning_("esp_ble_gattc_open", ret);
     this->set_state(espbt::ClientState::IDLE);
   } else {
     this->set_state(espbt::ClientState::CONNECTING);
@@ -140,14 +153,9 @@ void BLEClientBase::connect() {
 esp_err_t BLEClientBase::pair() { return esp_ble_set_encryption(this->remote_bda_, ESP_BLE_SEC_ENCRYPT); }
 
 void BLEClientBase::disconnect() {
-  if (this->state_ == espbt::ClientState::IDLE) {
-    ESP_LOGI(TAG, "[%d] [%s] Disconnect requested, but already idle.", this->connection_index_,
-             this->address_str_.c_str());
-    return;
-  }
-  if (this->state_ == espbt::ClientState::DISCONNECTING) {
-    ESP_LOGI(TAG, "[%d] [%s] Disconnect requested, but already disconnecting.", this->connection_index_,
-             this->address_str_.c_str());
+  if (this->state_ == espbt::ClientState::IDLE || this->state_ == espbt::ClientState::DISCONNECTING) {
+    ESP_LOGI(TAG, "[%d] [%s] Disconnect requested, but already %s", this->connection_index_, this->address_str_.c_str(),
+             espbt::client_state_to_string(this->state_));
     return;
   }
   if (this->state_ == espbt::ClientState::CONNECTING || this->conn_id_ == UNSET_CONN_ID) {
@@ -182,8 +190,7 @@ void BLEClientBase::unconditional_disconnect() {
     // In the future we might consider App.reboot() here since
     // the BLE stack is in an indeterminate state.
     //
-    ESP_LOGE(TAG, "[%d] [%s] esp_ble_gattc_close error, err=%d", this->connection_index_, this->address_str_.c_str(),
-             err);
+    this->log_gattc_warning_("esp_ble_gattc_close", err);
   }
 
   if (this->state_ == espbt::ClientState::SEARCHING || this->state_ == espbt::ClientState::READY_TO_CONNECT ||
@@ -196,9 +203,11 @@ void BLEClientBase::unconditional_disconnect() {
 }
 
 void BLEClientBase::release_services() {
+#ifdef USE_ESP32_BLE_DEVICE
   for (auto &svc : this->services_)
     delete svc;  // NOLINT(cppcoreguidelines-owning-memory)
   this->services_.clear();
+#endif
 #ifndef CONFIG_BT_GATTC_CACHE_NVS_FLASH
   esp_ble_gattc_cache_clean(this->remote_bda_);
 #endif
@@ -208,6 +217,36 @@ void BLEClientBase::log_event_(const char *name) {
   ESP_LOGD(TAG, "[%d] [%s] %s", this->connection_index_, this->address_str_.c_str(), name);
 }
 
+void BLEClientBase::log_gattc_event_(const char *name) {
+  ESP_LOGD(TAG, "[%d] [%s] ESP_GATTC_%s_EVT", this->connection_index_, this->address_str_.c_str(), name);
+}
+
+void BLEClientBase::log_gattc_warning_(const char *operation, esp_gatt_status_t status) {
+  ESP_LOGW(TAG, "[%d] [%s] %s error, status=%d", this->connection_index_, this->address_str_.c_str(), operation,
+           status);
+}
+
+void BLEClientBase::log_gattc_warning_(const char *operation, esp_err_t err) {
+  ESP_LOGW(TAG, "[%d] [%s] %s error, status=%d", this->connection_index_, this->address_str_.c_str(), operation, err);
+}
+
+void BLEClientBase::log_connection_params_(const char *param_type) {
+  ESP_LOGD(TAG, "[%d] [%s] %s conn params", this->connection_index_, this->address_str_.c_str(), param_type);
+}
+
+void BLEClientBase::restore_medium_conn_params_() {
+  // Restore to medium connection parameters after initial connection phase
+  // This balances performance with bandwidth usage for normal operation
+  esp_ble_conn_update_params_t conn_params = {{0}};
+  memcpy(conn_params.bda, this->remote_bda_, sizeof(esp_bd_addr_t));
+  conn_params.min_int = MEDIUM_MIN_CONN_INTERVAL;
+  conn_params.max_int = MEDIUM_MAX_CONN_INTERVAL;
+  conn_params.latency = 0;
+  conn_params.timeout = MEDIUM_CONN_TIMEOUT;
+  this->log_connection_params_("medium");
+  esp_ble_gap_update_conn_params(&conn_params);
+}
+
 bool BLEClientBase::gattc_event_handler(esp_gattc_cb_event_t event, esp_gatt_if_t esp_gattc_if,
                                         esp_ble_gattc_cb_param_t *param) {
   if (event == ESP_GATTC_REG_EVT && this->app_id != param->reg.app_id)
@@ -235,30 +274,18 @@ bool BLEClientBase::gattc_event_handler(esp_gattc_cb_event_t event, esp_gatt_if_
     case ESP_GATTC_OPEN_EVT: {
       if (!this->check_addr(param->open.remote_bda))
         return false;
-      this->log_event_("ESP_GATTC_OPEN_EVT");
-      this->conn_id_ = param->open.conn_id;
+      this->log_gattc_event_("OPEN");
+      // conn_id was already set in ESP_GATTC_CONNECT_EVT
       this->service_count_ = 0;
       if (this->state_ != espbt::ClientState::CONNECTING) {
         // This should not happen but lets log it in case it does
         // because it means we have a bad assumption about how the
         // ESP BT stack works.
-        if (this->state_ == espbt::ClientState::CONNECTED) {
-          ESP_LOGE(TAG, "[%d] [%s] Got ESP_GATTC_OPEN_EVT while already connected, status=%d", this->connection_index_,
-                   this->address_str_.c_str(), param->open.status);
-        } else if (this->state_ == espbt::ClientState::ESTABLISHED) {
-          ESP_LOGE(TAG, "[%d] [%s] Got ESP_GATTC_OPEN_EVT while already established, status=%d",
-                   this->connection_index_, this->address_str_.c_str(), param->open.status);
-        } else if (this->state_ == espbt::ClientState::DISCONNECTING) {
-          ESP_LOGE(TAG, "[%d] [%s] Got ESP_GATTC_OPEN_EVT while disconnecting, status=%d", this->connection_index_,
-                   this->address_str_.c_str(), param->open.status);
-        } else {
-          ESP_LOGE(TAG, "[%d] [%s] Got ESP_GATTC_OPEN_EVT while not in connecting state, status=%d",
-                   this->connection_index_, this->address_str_.c_str(), param->open.status);
-        }
+        ESP_LOGE(TAG, "[%d] [%s] Got ESP_GATTC_OPEN_EVT while in %s state, status=%d", this->connection_index_,
+                 this->address_str_.c_str(), espbt::client_state_to_string(this->state_), param->open.status);
       }
       if (param->open.status != ESP_GATT_OK && param->open.status != ESP_GATT_ALREADY_OPEN) {
-        ESP_LOGW(TAG, "[%d] [%s] Connection failed, status=%d", this->connection_index_, this->address_str_.c_str(),
-                 param->open.status);
+        this->log_gattc_warning_("Connection open", param->open.status);
         this->set_state(espbt::ClientState::IDLE);
         break;
       }
@@ -270,32 +297,47 @@ bool BLEClientBase::gattc_event_handler(esp_gattc_cb_event_t event, esp_gatt_if_
         this->conn_id_ = UNSET_CONN_ID;
         break;
       }
-      auto ret = esp_ble_gattc_send_mtu_req(this->gattc_if_, param->open.conn_id);
-      if (ret) {
-        ESP_LOGW(TAG, "[%d] [%s] esp_ble_gattc_send_mtu_req failed, status=%x", this->connection_index_,
-                 this->address_str_.c_str(), ret);
-      }
+      // MTU negotiation already started in ESP_GATTC_CONNECT_EVT
       this->set_state(espbt::ClientState::CONNECTED);
+      ESP_LOGI(TAG, "[%d] [%s] Connection open", this->connection_index_, this->address_str_.c_str());
       if (this->connection_type_ == espbt::ConnectionType::V3_WITH_CACHE) {
-        ESP_LOGI(TAG, "[%d] [%s] Connected", this->connection_index_, this->address_str_.c_str());
+        // Restore to medium connection parameters for cached connections too
+        this->restore_medium_conn_params_();
         // only set our state, subclients might have more stuff to do yet.
         this->state_ = espbt::ClientState::ESTABLISHED;
         break;
       }
+      ESP_LOGD(TAG, "[%d] [%s] Searching for services", this->connection_index_, this->address_str_.c_str());
       esp_ble_gattc_search_service(esp_gattc_if, param->cfg_mtu.conn_id, nullptr);
       break;
     }
     case ESP_GATTC_CONNECT_EVT: {
       if (!this->check_addr(param->connect.remote_bda))
         return false;
-      this->log_event_("ESP_GATTC_CONNECT_EVT");
+      this->log_gattc_event_("CONNECT");
+      this->conn_id_ = param->connect.conn_id;
+      // Start MTU negotiation immediately as recommended by ESP-IDF examples
+      // (gatt_client, ble_throughput) which call esp_ble_gattc_send_mtu_req in
+      // ESP_GATTC_CONNECT_EVT instead of waiting for ESP_GATTC_OPEN_EVT.
+      // This saves ~3ms in the connection process.
+      auto ret = esp_ble_gattc_send_mtu_req(this->gattc_if_, param->connect.conn_id);
+      if (ret) {
+        this->log_gattc_warning_("esp_ble_gattc_send_mtu_req", ret);
+      }
       break;
     }
     case ESP_GATTC_DISCONNECT_EVT: {
       if (!this->check_addr(param->disconnect.remote_bda))
         return false;
-      ESP_LOGD(TAG, "[%d] [%s] ESP_GATTC_DISCONNECT_EVT, reason %d", this->connection_index_,
-               this->address_str_.c_str(), param->disconnect.reason);
+      // Check if we were disconnected while waiting for service discovery
+      if (param->disconnect.reason == ESP_GATT_CONN_TERMINATE_PEER_USER &&
+          this->state_ == espbt::ClientState::CONNECTED) {
+        ESP_LOGW(TAG, "[%d] [%s] Disconnected by remote during service discovery", this->connection_index_,
+                 this->address_str_.c_str());
+      } else {
+        ESP_LOGD(TAG, "[%d] [%s] ESP_GATTC_DISCONNECT_EVT, reason 0x%02x", this->connection_index_,
+                 this->address_str_.c_str(), param->disconnect.reason);
+      }
       this->release_services();
       this->set_state(espbt::ClientState::IDLE);
       break;
@@ -318,7 +360,7 @@ bool BLEClientBase::gattc_event_handler(esp_gattc_cb_event_t event, esp_gatt_if_
     case ESP_GATTC_CLOSE_EVT: {
       if (this->conn_id_ != param->close.conn_id)
         return false;
-      this->log_event_("ESP_GATTC_CLOSE_EVT");
+      this->log_gattc_event_("CLOSE");
       this->release_services();
       this->set_state(espbt::ClientState::IDLE);
       this->conn_id_ = UNSET_CONN_ID;
@@ -330,63 +372,74 @@ bool BLEClientBase::gattc_event_handler(esp_gattc_cb_event_t event, esp_gatt_if_
       this->service_count_++;
       if (this->connection_type_ == espbt::ConnectionType::V3_WITHOUT_CACHE) {
         // V3 clients don't need services initialized since
-        // they only request by handle after receiving the services.
+        // as they use the ESP APIs to get services.
         break;
       }
+#ifdef USE_ESP32_BLE_DEVICE
       BLEService *ble_service = new BLEService();  // NOLINT(cppcoreguidelines-owning-memory)
       ble_service->uuid = espbt::ESPBTUUID::from_uuid(param->search_res.srvc_id.uuid);
       ble_service->start_handle = param->search_res.start_handle;
       ble_service->end_handle = param->search_res.end_handle;
       ble_service->client = this;
       this->services_.push_back(ble_service);
+#endif
       break;
     }
     case ESP_GATTC_SEARCH_CMPL_EVT: {
       if (this->conn_id_ != param->search_cmpl.conn_id)
         return false;
-      this->log_event_("ESP_GATTC_SEARCH_CMPL_EVT");
-      for (auto &svc : this->services_) {
-        ESP_LOGV(TAG, "[%d] [%s] Service UUID: %s", this->connection_index_, this->address_str_.c_str(),
-                 svc->uuid.to_string().c_str());
-        ESP_LOGV(TAG, "[%d] [%s]  start_handle: 0x%x  end_handle: 0x%x", this->connection_index_,
-                 this->address_str_.c_str(), svc->start_handle, svc->end_handle);
+      this->log_gattc_event_("SEARCH_CMPL");
+      // For V3 connections, restore to medium connection parameters after service discovery
+      // This balances performance with bandwidth usage after the critical discovery phase
+      if (this->connection_type_ == espbt::ConnectionType::V3_WITHOUT_CACHE ||
+          this->connection_type_ == espbt::ConnectionType::V3_WITH_CACHE) {
+        this->restore_medium_conn_params_();
+      } else {
+#ifdef USE_ESP32_BLE_DEVICE
+        for (auto &svc : this->services_) {
+          ESP_LOGV(TAG, "[%d] [%s] Service UUID: %s", this->connection_index_, this->address_str_.c_str(),
+                   svc->uuid.to_string().c_str());
+          ESP_LOGV(TAG, "[%d] [%s]  start_handle: 0x%x  end_handle: 0x%x", this->connection_index_,
+                   this->address_str_.c_str(), svc->start_handle, svc->end_handle);
+        }
+#endif
       }
-      ESP_LOGI(TAG, "[%d] [%s] Connected", this->connection_index_, this->address_str_.c_str());
+      ESP_LOGI(TAG, "[%d] [%s] Service discovery complete", this->connection_index_, this->address_str_.c_str());
       this->state_ = espbt::ClientState::ESTABLISHED;
       break;
     }
     case ESP_GATTC_READ_DESCR_EVT: {
       if (this->conn_id_ != param->write.conn_id)
         return false;
-      this->log_event_("ESP_GATTC_READ_DESCR_EVT");
+      this->log_gattc_event_("READ_DESCR");
       break;
     }
     case ESP_GATTC_WRITE_DESCR_EVT: {
       if (this->conn_id_ != param->write.conn_id)
         return false;
-      this->log_event_("ESP_GATTC_WRITE_DESCR_EVT");
+      this->log_gattc_event_("WRITE_DESCR");
       break;
     }
     case ESP_GATTC_WRITE_CHAR_EVT: {
       if (this->conn_id_ != param->write.conn_id)
         return false;
-      this->log_event_("ESP_GATTC_WRITE_CHAR_EVT");
+      this->log_gattc_event_("WRITE_CHAR");
       break;
     }
     case ESP_GATTC_READ_CHAR_EVT: {
       if (this->conn_id_ != param->read.conn_id)
         return false;
-      this->log_event_("ESP_GATTC_READ_CHAR_EVT");
+      this->log_gattc_event_("READ_CHAR");
       break;
     }
     case ESP_GATTC_NOTIFY_EVT: {
       if (this->conn_id_ != param->notify.conn_id)
         return false;
-      this->log_event_("ESP_GATTC_NOTIFY_EVT");
+      this->log_gattc_event_("NOTIFY");
       break;
     }
     case ESP_GATTC_REG_FOR_NOTIFY_EVT: {
-      this->log_event_("ESP_GATTC_REG_FOR_NOTIFY_EVT");
+      this->log_gattc_event_("REG_FOR_NOTIFY");
       if (this->connection_type_ == espbt::ConnectionType::V3_WITH_CACHE ||
           this->connection_type_ == espbt::ConnectionType::V3_WITHOUT_CACHE) {
         // Client is responsible for flipping the descriptor value
@@ -398,8 +451,7 @@ bool BLEClientBase::gattc_event_handler(esp_gattc_cb_event_t event, esp_gatt_if_
       esp_gatt_status_t descr_status = esp_ble_gattc_get_descr_by_char_handle(
           this->gattc_if_, this->conn_id_, param->reg_for_notify.handle, NOTIFY_DESC_UUID, &desc_result, &count);
       if (descr_status != ESP_GATT_OK) {
-        ESP_LOGW(TAG, "[%d] [%s] esp_ble_gattc_get_descr_by_char_handle error, status=%d", this->connection_index_,
-                 this->address_str_.c_str(), descr_status);
+        this->log_gattc_warning_("esp_ble_gattc_get_descr_by_char_handle", descr_status);
         break;
       }
       esp_gattc_char_elem_t char_result;
@@ -407,8 +459,7 @@ bool BLEClientBase::gattc_event_handler(esp_gattc_cb_event_t event, esp_gatt_if_
           esp_ble_gattc_get_all_char(this->gattc_if_, this->conn_id_, param->reg_for_notify.handle,
                                      param->reg_for_notify.handle, &char_result, &count, 0);
       if (char_status != ESP_GATT_OK) {
-        ESP_LOGW(TAG, "[%d] [%s] esp_ble_gattc_get_all_char error, status=%d", this->connection_index_,
-                 this->address_str_.c_str(), char_status);
+        this->log_gattc_warning_("esp_ble_gattc_get_all_char", char_status);
         break;
       }
 
@@ -422,8 +473,7 @@ bool BLEClientBase::gattc_event_handler(esp_gattc_cb_event_t event, esp_gatt_if_
                                          (uint8_t *) &notify_en, ESP_GATT_WRITE_TYPE_RSP, ESP_GATT_AUTH_REQ_NONE);
       ESP_LOGD(TAG, "Wrote notify descriptor %d, properties=%d", notify_en, char_result.properties);
       if (status) {
-        ESP_LOGW(TAG, "[%d] [%s] esp_ble_gattc_write_char_descr error, status=%d", this->connection_index_,
-                 this->address_str_.c_str(), status);
+        this->log_gattc_warning_("esp_ble_gattc_write_char_descr", status);
       }
       break;
     }
@@ -531,6 +581,7 @@ float BLEClientBase::parse_char_value(uint8_t *value, uint16_t length) {
   return NAN;
 }
 
+#ifdef USE_ESP32_BLE_DEVICE
 BLEService *BLEClientBase::get_service(espbt::ESPBTUUID uuid) {
   for (auto *svc : this->services_) {
     if (svc->uuid == uuid)
@@ -607,8 +658,8 @@ BLEDescriptor *BLEClientBase::get_descriptor(uint16_t handle) {
   }
   return nullptr;
 }
+#endif  // USE_ESP32_BLE_DEVICE
 
-}  // namespace esp32_ble_client
-}  // namespace esphome
+}  // namespace esphome::esp32_ble_client
 
 #endif  // USE_ESP32

esphome/components/esp32_ble_client/ble_client_base.h

@@ -5,7 +5,9 @@
 #include "esphome/components/esp32_ble_tracker/esp32_ble_tracker.h"
 #include "esphome/core/component.h"
 
+#ifdef USE_ESP32_BLE_DEVICE
 #include "ble_service.h"
+#endif
 
 #include <array>
 #include <string>
@@ -16,8 +18,7 @@
 #include <esp_gatt_common_api.h>
 #include <esp_gattc_api.h>
 
-namespace esphome {
-namespace esp32_ble_client {
+namespace esphome::esp32_ble_client {
 
 namespace espbt = esphome::esp32_ble_tracker;
 
@@ -31,7 +32,9 @@ class BLEClientBase : public espbt::ESPBTClient, public Component {
   void dump_config() override;
 
   void run_later(std::function<void()> &&f);  // NOLINT
+#ifdef USE_ESP32_BLE_DEVICE
   bool parse_device(const espbt::ESPBTDevice &device) override;
+#endif
   void on_scan_end() override {}
   bool gattc_event_handler(esp_gattc_cb_event_t event, esp_gatt_if_t gattc_if,
                            esp_ble_gattc_cb_param_t *param) override;
@@ -46,7 +49,7 @@ class BLEClientBase : public espbt::ESPBTClient, public Component {
 
   void set_auto_connect(bool auto_connect) { this->auto_connect_ = auto_connect; }
 
-  void set_address(uint64_t address) {
+  virtual void set_address(uint64_t address) {
     this->address_ = address;
     this->remote_bda_[0] = (address >> 40) & 0xFF;
     this->remote_bda_[1] = (address >> 32) & 0xFF;
@@ -64,8 +67,9 @@ class BLEClientBase : public espbt::ESPBTClient, public Component {
                        (uint8_t) (this->address_ >> 0) & 0xff);
     }
   }
-  std::string address_str() const { return this->address_str_; }
+  const std::string &address_str() const { return this->address_str_; }
 
+#ifdef USE_ESP32_BLE_DEVICE
   BLEService *get_service(espbt::ESPBTUUID uuid);
   BLEService *get_service(uint16_t uuid);
   BLECharacteristic *get_characteristic(espbt::ESPBTUUID service, espbt::ESPBTUUID chr);
@@ -76,6 +80,7 @@ class BLEClientBase : public espbt::ESPBTClient, public Component {
   BLEDescriptor *get_descriptor(uint16_t handle);
   // Get the configuration descriptor for the given characteristic handle.
   BLEDescriptor *get_config_descriptor(uint16_t handle);
+#endif
 
   float parse_char_value(uint8_t *value, uint16_t length);
 
@@ -102,7 +107,9 @@ class BLEClientBase : public espbt::ESPBTClient, public Component {
 
   // Group 2: Container types (grouped for memory optimization)
   std::string address_str_{};
+#ifdef USE_ESP32_BLE_DEVICE
   std::vector<BLEService *> services_;
+#endif
 
   // Group 3: 4-byte types
   int gattc_if_;
@@ -125,9 +132,13 @@ class BLEClientBase : public espbt::ESPBTClient, public Component {
   // 6 bytes used, 2 bytes padding
 
   void log_event_(const char *name);
+  void log_gattc_event_(const char *name);
+  void restore_medium_conn_params_();
+  void log_gattc_warning_(const char *operation, esp_gatt_status_t status);
+  void log_gattc_warning_(const char *operation, esp_err_t err);
+  void log_connection_params_(const char *param_type);
 };
 
-}  // namespace esp32_ble_client
-}  // namespace esphome
+}  // namespace esphome::esp32_ble_client
 
 #endif  // USE_ESP32

esphome/components/esp32_ble_client/ble_descriptor.h

@@ -1,11 +1,13 @@
 #pragma once
 
+#include "esphome/core/defines.h"
+
 #ifdef USE_ESP32
+#ifdef USE_ESP32_BLE_DEVICE
 
 #include "esphome/components/esp32_ble_tracker/esp32_ble_tracker.h"
 
-namespace esphome {
-namespace esp32_ble_client {
+namespace esphome::esp32_ble_client {
 
 namespace espbt = esphome::esp32_ble_tracker;
 
@@ -19,7 +21,7 @@ class BLEDescriptor {
   BLECharacteristic *characteristic;
 };
 
-}  // namespace esp32_ble_client
-}  // namespace esphome
+}  // namespace esphome::esp32_ble_client
 
+#endif  // USE_ESP32_BLE_DEVICE
 #endif  // USE_ESP32

esphome/components/esp32_ble_client/ble_service.cpp

@@ -4,9 +4,9 @@
 #include "esphome/core/log.h"
 
 #ifdef USE_ESP32
+#ifdef USE_ESP32_BLE_DEVICE
 
-namespace esphome {
-namespace esp32_ble_client {
+namespace esphome::esp32_ble_client {
 
 static const char *const TAG = "esp32_ble_client";
 
@@ -71,7 +71,7 @@ void BLEService::parse_characteristics() {
   }
 }
 
-}  // namespace esp32_ble_client
-}  // namespace esphome
+}  // namespace esphome::esp32_ble_client
 
+#endif  // USE_ESP32_BLE_DEVICE
 #endif  // USE_ESP32

esphome/components/esp32_ble_client/ble_service.h

@@ -1,6 +1,9 @@
 #pragma once
 
+#include "esphome/core/defines.h"
+
 #ifdef USE_ESP32
+#ifdef USE_ESP32_BLE_DEVICE
 
 #include "esphome/components/esp32_ble_tracker/esp32_ble_tracker.h"
 
@@ -8,8 +11,7 @@
 
 #include <vector>
 
-namespace esphome {
-namespace esp32_ble_client {
+namespace esphome::esp32_ble_client {
 
 namespace espbt = esphome::esp32_ble_tracker;
 
@@ -30,7 +32,7 @@ class BLEService {
   BLECharacteristic *get_characteristic(uint16_t uuid);
 };
 
-}  // namespace esp32_ble_client
-}  // namespace esphome
+}  // namespace esphome::esp32_ble_client
 
+#endif  // USE_ESP32_BLE_DEVICE
 #endif  // USE_ESP32