[bluetooth_proxy] Add BLE connection parameters API

Add support for setting BLE connection parameters (min/max interval,
latency, supervision timeout) on connected devices via the native API.
This allows integrations like yalexs-ble to reduce battery drain on
"Always Connected" BLE devices by switching from fast connection intervals
to slower ones after connection is established.

Adds new BluetoothSetConnectionParamsRequest/Response protobuf messages
(IDs 145/146) and routes them through the bluetooth proxy to call
esp_ble_gap_update_conn_params() on the ESP32.

Related: home-assistant/core#153977

esphome/components/api/api.proto

@@ -2517,3 +2517,26 @@ message InfraredRFReceiveEvent {
   fixed32 key = 2;                                    // Key identifying the receiver instance
   repeated sint32 timings = 3 [packed = true, (container_pointer_no_template) = "std::vector<int32_t>"];  // Raw timings in microseconds (zigzag-encoded): alternating mark/space periods
 }
+
+// ==================== Bluetooth Connection Parameters ====================
+
+message BluetoothSetConnectionParamsRequest {
+  option (id) = 145;
+  option (source) = SOURCE_CLIENT;
+  option (ifdef) = "USE_BLUETOOTH_PROXY";
+
+  uint64 address = 1;
+  uint32 min_interval = 2;  // units of 1.25ms
+  uint32 max_interval = 3;  // units of 1.25ms
+  uint32 latency = 4;
+  uint32 timeout = 5;       // units of 10ms
+}
+
+message BluetoothSetConnectionParamsResponse {
+  option (id) = 146;
+  option (source) = SOURCE_SERVER;
+  option (ifdef) = "USE_BLUETOOTH_PROXY";
+
+  uint64 address = 1;
+  int32 error = 2;
+}

esphome/components/api/api_connection.cpp

@@ -1188,6 +1188,9 @@ void APIConnection::on_bluetooth_scanner_set_mode_request(const BluetoothScanner
   bluetooth_proxy::global_bluetooth_proxy->bluetooth_scanner_set_mode(
       msg.mode == enums::BluetoothScannerMode::BLUETOOTH_SCANNER_MODE_ACTIVE);
 }
+void APIConnection::on_bluetooth_set_connection_params_request(const BluetoothSetConnectionParamsRequest &msg) {
+  bluetooth_proxy::global_bluetooth_proxy->bluetooth_set_connection_params(msg);
+}
 #endif
 
 #ifdef USE_VOICE_ASSISTANT

esphome/components/api/api_connection.h

@@ -148,6 +148,7 @@ class APIConnection final : public APIServerConnectionBase {
   void on_bluetooth_gatt_notify_request(const BluetoothGATTNotifyRequest &msg) override;
   void on_subscribe_bluetooth_connections_free_request() override;
   void on_bluetooth_scanner_set_mode_request(const BluetoothScannerSetModeRequest &msg) override;
+  void on_bluetooth_set_connection_params_request(const BluetoothSetConnectionParamsRequest &msg) override;
 
 #endif
 #ifdef USE_HOMEASSISTANT_TIME

esphome/components/api/api_pb2.cpp

@@ -3714,5 +3714,39 @@ uint32_t InfraredRFReceiveEvent::calculate_size() const {
   return size;
 }
 #endif
+#ifdef USE_BLUETOOTH_PROXY
+bool BluetoothSetConnectionParamsRequest::decode_varint(uint32_t field_id, ProtoVarInt value) {
+  switch (field_id) {
+    case 1:
+      this->address = value.as_uint64();
+      break;
+    case 2:
+      this->min_interval = value.as_uint32();
+      break;
+    case 3:
+      this->max_interval = value.as_uint32();
+      break;
+    case 4:
+      this->latency = value.as_uint32();
+      break;
+    case 5:
+      this->timeout = value.as_uint32();
+      break;
+    default:
+      return false;
+  }
+  return true;
+}
+void BluetoothSetConnectionParamsResponse::encode(ProtoWriteBuffer &buffer) const {
+  buffer.encode_uint64(1, this->address);
+  buffer.encode_int32(2, this->error);
+}
+uint32_t BluetoothSetConnectionParamsResponse::calculate_size() const {
+  uint32_t size = 0;
+  size += ProtoSize::calc_uint64(1, this->address);
+  size += ProtoSize::calc_int32(1, this->error);
+  return size;
+}
+#endif
 
 }  // namespace esphome::api

esphome/components/api/api_pb2.h

@@ -3061,5 +3061,43 @@ class InfraredRFReceiveEvent final : public ProtoMessage {
  protected:
 };
 #endif
+#ifdef USE_BLUETOOTH_PROXY
+class BluetoothSetConnectionParamsRequest final : public ProtoDecodableMessage {
+ public:
+  static constexpr uint8_t MESSAGE_TYPE = 145;
+  static constexpr uint8_t ESTIMATED_SIZE = 20;
+#ifdef HAS_PROTO_MESSAGE_DUMP
+  const char *message_name() const override { return "bluetooth_set_connection_params_request"; }
+#endif
+  uint64_t address{0};
+  uint32_t min_interval{0};
+  uint32_t max_interval{0};
+  uint32_t latency{0};
+  uint32_t timeout{0};
+#ifdef HAS_PROTO_MESSAGE_DUMP
+  const char *dump_to(DumpBuffer &out) const override;
+#endif
+
+ protected:
+  bool decode_varint(uint32_t field_id, ProtoVarInt value) override;
+};
+class BluetoothSetConnectionParamsResponse final : public ProtoMessage {
+ public:
+  static constexpr uint8_t MESSAGE_TYPE = 146;
+  static constexpr uint8_t ESTIMATED_SIZE = 8;
+#ifdef HAS_PROTO_MESSAGE_DUMP
+  const char *message_name() const override { return "bluetooth_set_connection_params_response"; }
+#endif
+  uint64_t address{0};
+  int32_t error{0};
+  void encode(ProtoWriteBuffer &buffer) const;
+  uint32_t calculate_size() const;
+#ifdef HAS_PROTO_MESSAGE_DUMP
+  const char *dump_to(DumpBuffer &out) const override;
+#endif
+
+ protected:
+};
+#endif
 
 }  // namespace esphome::api

esphome/components/api/api_pb2_dump.cpp

@@ -2510,6 +2510,23 @@ const char *InfraredRFReceiveEvent::dump_to(DumpBuffer &out) const {
   return out.c_str();
 }
 #endif
+#ifdef USE_BLUETOOTH_PROXY
+const char *BluetoothSetConnectionParamsRequest::dump_to(DumpBuffer &out) const {
+  MessageDumpHelper helper(out, "BluetoothSetConnectionParamsRequest");
+  dump_field(out, "address", this->address);
+  dump_field(out, "min_interval", this->min_interval);
+  dump_field(out, "max_interval", this->max_interval);
+  dump_field(out, "latency", this->latency);
+  dump_field(out, "timeout", this->timeout);
+  return out.c_str();
+}
+const char *BluetoothSetConnectionParamsResponse::dump_to(DumpBuffer &out) const {
+  MessageDumpHelper helper(out, "BluetoothSetConnectionParamsResponse");
+  dump_field(out, "address", this->address);
+  dump_field(out, "error", this->error);
+  return out.c_str();
+}
+#endif
 
 }  // namespace esphome::api
 

esphome/components/api/api_pb2_service.cpp

@@ -634,6 +634,17 @@ void APIServerConnectionBase::read_message(uint32_t msg_size, uint32_t msg_type,
       this->on_infrared_rf_transmit_raw_timings_request(msg);
       break;
     }
+#endif
+#ifdef USE_BLUETOOTH_PROXY
+    case BluetoothSetConnectionParamsRequest::MESSAGE_TYPE: {
+      BluetoothSetConnectionParamsRequest msg;
+      msg.decode(msg_data, msg_size);
+#ifdef HAS_PROTO_MESSAGE_DUMP
+      this->log_receive_message_(LOG_STR("on_bluetooth_set_connection_params_request"), msg);
+#endif
+      this->on_bluetooth_set_connection_params_request(msg);
+      break;
+    }
 #endif
     default:
       break;

esphome/components/api/api_pb2_service.h

@@ -216,6 +216,10 @@ class APIServerConnectionBase : public ProtoService {
   virtual void on_infrared_rf_transmit_raw_timings_request(const InfraredRFTransmitRawTimingsRequest &value){};
 #endif
 
+#ifdef USE_BLUETOOTH_PROXY
+  virtual void on_bluetooth_set_connection_params_request(const BluetoothSetConnectionParamsRequest &value){};
+#endif
+
  protected:
   void read_message(uint32_t msg_size, uint32_t msg_type, const uint8_t *msg_data) override;
 };

esphome/components/bluetooth_proxy/bluetooth_connection.h

@@ -24,6 +24,10 @@ class BluetoothConnection final : public esp32_ble_client::BLEClientBase {
 
   esp_err_t notify_characteristic(uint16_t handle, bool enable);
 
+  void update_connection_params(uint16_t min_interval, uint16_t max_interval, uint16_t latency, uint16_t timeout) {
+    this->update_conn_params_(min_interval, max_interval, latency, timeout, "custom");
+  }
+
   void set_address(uint64_t address) override;
 
  protected:

esphome/components/bluetooth_proxy/bluetooth_proxy.cpp

@@ -361,6 +361,23 @@ void BluetoothProxy::bluetooth_gatt_notify(const api::BluetoothGATTNotifyRequest
   }
 }
 
+void BluetoothProxy::bluetooth_set_connection_params(const api::BluetoothSetConnectionParamsRequest &msg) {
+  auto *connection = this->get_connection_(msg.address, false);
+  api::BluetoothSetConnectionParamsResponse resp;
+  resp.address = msg.address;
+
+  if (connection == nullptr || !connection->connected()) {
+    ESP_LOGW(TAG, "Cannot set connection params, not connected");
+    resp.error = ESP_GATT_NOT_CONNECTED;
+    this->api_connection_->send_message(resp);
+    return;
+  }
+
+  connection->update_connection_params(msg.min_interval, msg.max_interval, msg.latency, msg.timeout);
+  resp.error = ESP_OK;
+  this->api_connection_->send_message(resp);
+}
+
 void BluetoothProxy::subscribe_api_connection(api::APIConnection *api_connection, uint32_t flags) {
   if (this->api_connection_ != nullptr) {
     ESP_LOGE(TAG, "Only one API subscription is allowed at a time");

esphome/components/bluetooth_proxy/bluetooth_proxy.h

@@ -46,6 +46,7 @@ enum BluetoothProxyFeature : uint32_t {
   FEATURE_CACHE_CLEARING = 1 << 4,
   FEATURE_RAW_ADVERTISEMENTS = 1 << 5,
   FEATURE_STATE_AND_MODE = 1 << 6,
+  FEATURE_CONNECTION_PARAMS_SETTING = 1 << 7,
 };
 
 enum BluetoothProxySubscriptionFlag : uint32_t {
@@ -82,6 +83,7 @@ class BluetoothProxy final : public esp32_ble_tracker::ESPBTDeviceListener,
   void bluetooth_gatt_write_descriptor(const api::BluetoothGATTWriteDescriptorRequest &msg);
   void bluetooth_gatt_send_services(const api::BluetoothGATTGetServicesRequest &msg);
   void bluetooth_gatt_notify(const api::BluetoothGATTNotifyRequest &msg);
+  void bluetooth_set_connection_params(const api::BluetoothSetConnectionParamsRequest &msg);
 
   void subscribe_api_connection(api::APIConnection *api_connection, uint32_t flags);
   void unsubscribe_api_connection(api::APIConnection *api_connection);
@@ -130,6 +132,7 @@ class BluetoothProxy final : public esp32_ble_tracker::ESPBTDeviceListener,
       flags |= BluetoothProxyFeature::FEATURE_REMOTE_CACHING;
       flags |= BluetoothProxyFeature::FEATURE_PAIRING;
       flags |= BluetoothProxyFeature::FEATURE_CACHE_CLEARING;
+      flags |= BluetoothProxyFeature::FEATURE_CONNECTION_PARAMS_SETTING;
     }
 
     return flags;