[serial_proxy] New component (#13944)

Co-authored-by: J. Nick Koston <nick@koston.org>
Co-authored-by: pre-commit-ci-lite[bot] <117423508+pre-commit-ci-lite[bot]@users.noreply.github.com>
Co-authored-by: J. Nick Koston <nick@home-assistant.io>

CODEOWNERS

@@ -435,6 +435,7 @@ esphome/components/sen5x/* @martgras
 esphome/components/sen6x/* @martgras @mebner86 @mikelawrence @tuct
 esphome/components/sensirion_common/* @martgras
 esphome/components/sensor/* @esphome/core
+esphome/components/serial_proxy/* @kbx81
 esphome/components/sfa30/* @ghsensdev
 esphome/components/sgp40/* @SenexCrenshaw
 esphome/components/sgp4x/* @martgras @SenexCrenshaw

esphome/components/api/api.proto

@@ -2618,6 +2618,14 @@ enum SerialProxyRequestType {
   SERIAL_PROXY_REQUEST_TYPE_FLUSH = 2;       // Flush the serial port (block until all TX data is sent)
 }
 
+enum SerialProxyStatus {
+  SERIAL_PROXY_STATUS_OK = 0;              // Completed successfully; TX drain confirmed
+  SERIAL_PROXY_STATUS_ASSUMED_SUCCESS = 1; // Platform cannot confirm TX drain; success assumed
+  SERIAL_PROXY_STATUS_ERROR = 2;           // Driver or hardware error
+  SERIAL_PROXY_STATUS_TIMEOUT = 3;         // Timed out before TX completed
+  SERIAL_PROXY_STATUS_NOT_SUPPORTED = 4;   // Request type not supported by this instance
+}
+
 // Generic request message for simple serial proxy operations
 message SerialProxyRequest {
   option (id) = 144;
@@ -2628,6 +2636,18 @@ message SerialProxyRequest {
   SerialProxyRequestType type = 2;      // Request type
 }
 
+// Response to a SerialProxyRequest (e.g. flush completion or failure)
+message SerialProxyRequestResponse {
+  option (id) = 147;
+  option (source) = SOURCE_SERVER;
+  option (ifdef) = "USE_SERIAL_PROXY";
+
+  uint32 instance = 1;                  // Instance index (0-based)
+  SerialProxyRequestType type = 2;      // Which request type this responds to
+  SerialProxyStatus status = 3;         // Result status
+  string error_message = 4;            // Additional detail on failure (optional)
+}
+
 // ==================== BLUETOOTH CONNECTION PARAMS ====================
 message BluetoothSetConnectionParamsRequest {
   option (id) = 145;

esphome/components/api/api_connection.cpp

@@ -1445,6 +1445,89 @@ void APIConnection::on_infrared_rf_transmit_raw_timings_request(const InfraredRF
 void APIConnection::send_infrared_rf_receive_event(const InfraredRFReceiveEvent &msg) { this->send_message(msg); }
 #endif
 
+#ifdef USE_SERIAL_PROXY
+void APIConnection::on_serial_proxy_configure_request(const SerialProxyConfigureRequest &msg) {
+  auto &proxies = App.get_serial_proxies();
+  if (msg.instance >= proxies.size()) {
+    ESP_LOGW(TAG, "Serial proxy instance %u out of range (max %u)", msg.instance,
+             static_cast<uint32_t>(proxies.size()));
+    return;
+  }
+  proxies[msg.instance]->configure(msg.baudrate, msg.flow_control, static_cast<uint8_t>(msg.parity), msg.stop_bits,
+                                   msg.data_size);
+}
+
+void APIConnection::on_serial_proxy_write_request(const SerialProxyWriteRequest &msg) {
+  auto &proxies = App.get_serial_proxies();
+  if (msg.instance >= proxies.size()) {
+    ESP_LOGW(TAG, "Serial proxy instance %u out of range", msg.instance);
+    return;
+  }
+  proxies[msg.instance]->write_from_client(msg.data, msg.data_len);
+}
+
+void APIConnection::on_serial_proxy_set_modem_pins_request(const SerialProxySetModemPinsRequest &msg) {
+  auto &proxies = App.get_serial_proxies();
+  if (msg.instance >= proxies.size()) {
+    ESP_LOGW(TAG, "Serial proxy instance %u out of range", msg.instance);
+    return;
+  }
+  proxies[msg.instance]->set_modem_pins(msg.line_states);
+}
+
+void APIConnection::on_serial_proxy_get_modem_pins_request(const SerialProxyGetModemPinsRequest &msg) {
+  auto &proxies = App.get_serial_proxies();
+  if (msg.instance >= proxies.size()) {
+    ESP_LOGW(TAG, "Serial proxy instance %u out of range", msg.instance);
+    return;
+  }
+  SerialProxyGetModemPinsResponse resp{};
+  resp.instance = msg.instance;
+  resp.line_states = proxies[msg.instance]->get_modem_pins();
+  this->send_message(resp);
+}
+
+void APIConnection::on_serial_proxy_request(const SerialProxyRequest &msg) {
+  auto &proxies = App.get_serial_proxies();
+  if (msg.instance >= proxies.size()) {
+    ESP_LOGW(TAG, "Serial proxy instance %u out of range", msg.instance);
+    return;
+  }
+  switch (msg.type) {
+    case enums::SERIAL_PROXY_REQUEST_TYPE_SUBSCRIBE:
+    case enums::SERIAL_PROXY_REQUEST_TYPE_UNSUBSCRIBE:
+      proxies[msg.instance]->serial_proxy_request(this, msg.type);
+      break;
+    case enums::SERIAL_PROXY_REQUEST_TYPE_FLUSH: {
+      SerialProxyRequestResponse resp{};
+      resp.instance = msg.instance;
+      resp.type = enums::SERIAL_PROXY_REQUEST_TYPE_FLUSH;
+      switch (proxies[msg.instance]->flush_port()) {
+        case uart::FlushResult::SUCCESS:
+          resp.status = enums::SERIAL_PROXY_STATUS_OK;
+          break;
+        case uart::FlushResult::ASSUMED_SUCCESS:
+          resp.status = enums::SERIAL_PROXY_STATUS_ASSUMED_SUCCESS;
+          break;
+        case uart::FlushResult::TIMEOUT:
+          resp.status = enums::SERIAL_PROXY_STATUS_TIMEOUT;
+          break;
+        case uart::FlushResult::FAILED:
+          resp.status = enums::SERIAL_PROXY_STATUS_ERROR;
+          break;
+      }
+      this->send_message(resp);
+      break;
+    }
+    default:
+      ESP_LOGW(TAG, "Unknown serial proxy request type: %u", static_cast<uint32_t>(msg.type));
+      break;
+  }
+}
+
+void APIConnection::send_serial_proxy_data(const SerialProxyDataReceived &msg) { this->send_message(msg); }
+#endif
+
 #ifdef USE_INFRARED
 uint16_t APIConnection::try_send_infrared_info(EntityBase *entity, APIConnection *conn, uint32_t remaining_size) {
   auto *infrared = static_cast<infrared::Infrared *>(entity);
@@ -1666,6 +1749,16 @@ bool APIConnection::send_device_info_response_() {
   resp.zwave_proxy_feature_flags = zwave_proxy::global_zwave_proxy->get_feature_flags();
   resp.zwave_home_id = zwave_proxy::global_zwave_proxy->get_home_id();
 #endif
+#ifdef USE_SERIAL_PROXY
+  size_t serial_proxy_index = 0;
+  for (auto const &proxy : App.get_serial_proxies()) {
+    if (serial_proxy_index >= SERIAL_PROXY_COUNT)
+      break;
+    auto &info = resp.serial_proxies[serial_proxy_index++];
+    info.name = StringRef(proxy->get_name());
+    info.port_type = proxy->get_port_type();
+  }
+#endif
 #ifdef USE_API_NOISE
   resp.api_encryption_supported = true;
 #endif

esphome/components/api/api_connection.h

@@ -189,6 +189,15 @@ class APIConnection final : public APIServerConnectionBase {
   void send_infrared_rf_receive_event(const InfraredRFReceiveEvent &msg);
 #endif
 
+#ifdef USE_SERIAL_PROXY
+  void on_serial_proxy_configure_request(const SerialProxyConfigureRequest &msg) override;
+  void on_serial_proxy_write_request(const SerialProxyWriteRequest &msg) override;
+  void on_serial_proxy_set_modem_pins_request(const SerialProxySetModemPinsRequest &msg) override;
+  void on_serial_proxy_get_modem_pins_request(const SerialProxyGetModemPinsRequest &msg) override;
+  void on_serial_proxy_request(const SerialProxyRequest &msg) override;
+  void send_serial_proxy_data(const SerialProxyDataReceived &msg);
+#endif
+
 #ifdef USE_EVENT
   void send_event(event::Event *event);
 #endif
@@ -254,6 +263,7 @@ class APIConnection final : public APIServerConnectionBase {
     return static_cast<ConnectionState>(this->flags_.connection_state) == ConnectionState::CONNECTED ||
            this->is_authenticated();
   }
+  bool is_marked_for_removal() const { return this->flags_.remove; }
   uint8_t get_log_subscription_level() const { return this->flags_.log_subscription; }
 
   // Get client API version for feature detection

esphome/components/api/api_pb2.cpp

@@ -3840,6 +3840,20 @@ bool SerialProxyRequest::decode_varint(uint32_t field_id, ProtoVarInt value) {
   }
   return true;
 }
+void SerialProxyRequestResponse::encode(ProtoWriteBuffer &buffer) const {
+  buffer.encode_uint32(1, this->instance);
+  buffer.encode_uint32(2, static_cast<uint32_t>(this->type));
+  buffer.encode_uint32(3, static_cast<uint32_t>(this->status));
+  buffer.encode_string(4, this->error_message);
+}
+uint32_t SerialProxyRequestResponse::calculate_size() const {
+  uint32_t size = 0;
+  size += ProtoSize::calc_uint32(1, this->instance);
+  size += ProtoSize::calc_uint32(1, static_cast<uint32_t>(this->type));
+  size += ProtoSize::calc_uint32(1, static_cast<uint32_t>(this->status));
+  size += ProtoSize::calc_length(1, this->error_message.size());
+  return size;
+}
 #endif
 #ifdef USE_BLUETOOTH_PROXY
 bool BluetoothSetConnectionParamsRequest::decode_varint(uint32_t field_id, ProtoVarInt value) {

esphome/components/api/api_pb2.h

@@ -333,6 +333,13 @@ enum SerialProxyRequestType : uint32_t {
   SERIAL_PROXY_REQUEST_TYPE_UNSUBSCRIBE = 1,
   SERIAL_PROXY_REQUEST_TYPE_FLUSH = 2,
 };
+enum SerialProxyStatus : uint32_t {
+  SERIAL_PROXY_STATUS_OK = 0,
+  SERIAL_PROXY_STATUS_ASSUMED_SUCCESS = 1,
+  SERIAL_PROXY_STATUS_ERROR = 2,
+  SERIAL_PROXY_STATUS_TIMEOUT = 3,
+  SERIAL_PROXY_STATUS_NOT_SUPPORTED = 4,
+};
 #endif
 
 }  // namespace enums
@@ -3220,6 +3227,25 @@ class SerialProxyRequest final : public ProtoDecodableMessage {
  protected:
   bool decode_varint(uint32_t field_id, ProtoVarInt value) override;
 };
+class SerialProxyRequestResponse final : public ProtoMessage {
+ public:
+  static constexpr uint8_t MESSAGE_TYPE = 147;
+  static constexpr uint8_t ESTIMATED_SIZE = 17;
+#ifdef HAS_PROTO_MESSAGE_DUMP
+  const char *message_name() const override { return "serial_proxy_request_response"; }
+#endif
+  uint32_t instance{0};
+  enums::SerialProxyRequestType type{};
+  enums::SerialProxyStatus status{};
+  StringRef error_message{};
+  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
 #ifdef USE_BLUETOOTH_PROXY
 class BluetoothSetConnectionParamsRequest final : public ProtoDecodableMessage {

esphome/components/api/api_pb2_dump.cpp

@@ -789,6 +789,22 @@ template<> const char *proto_enum_to_string<enums::SerialProxyRequestType>(enums
       return "UNKNOWN";
   }
 }
+template<> const char *proto_enum_to_string<enums::SerialProxyStatus>(enums::SerialProxyStatus value) {
+  switch (value) {
+    case enums::SERIAL_PROXY_STATUS_OK:
+      return "SERIAL_PROXY_STATUS_OK";
+    case enums::SERIAL_PROXY_STATUS_ASSUMED_SUCCESS:
+      return "SERIAL_PROXY_STATUS_ASSUMED_SUCCESS";
+    case enums::SERIAL_PROXY_STATUS_ERROR:
+      return "SERIAL_PROXY_STATUS_ERROR";
+    case enums::SERIAL_PROXY_STATUS_TIMEOUT:
+      return "SERIAL_PROXY_STATUS_TIMEOUT";
+    case enums::SERIAL_PROXY_STATUS_NOT_SUPPORTED:
+      return "SERIAL_PROXY_STATUS_NOT_SUPPORTED";
+    default:
+      return "UNKNOWN";
+  }
+}
 #endif
 
 const char *HelloRequest::dump_to(DumpBuffer &out) const {
@@ -2609,6 +2625,14 @@ const char *SerialProxyRequest::dump_to(DumpBuffer &out) const {
   dump_field(out, "type", static_cast<enums::SerialProxyRequestType>(this->type));
   return out.c_str();
 }
+const char *SerialProxyRequestResponse::dump_to(DumpBuffer &out) const {
+  MessageDumpHelper helper(out, "SerialProxyRequestResponse");
+  dump_field(out, "instance", this->instance);
+  dump_field(out, "type", static_cast<enums::SerialProxyRequestType>(this->type));
+  dump_field(out, "status", static_cast<enums::SerialProxyStatus>(this->status));
+  dump_field(out, "error_message", this->error_message);
+  return out.c_str();
+}
 #endif
 #ifdef USE_BLUETOOTH_PROXY
 const char *BluetoothSetConnectionParamsRequest::dump_to(DumpBuffer &out) const {

esphome/components/api/api_pb2_service.h

@@ -233,6 +233,7 @@ class APIServerConnectionBase : public ProtoService {
 #ifdef USE_SERIAL_PROXY
   virtual void on_serial_proxy_request(const SerialProxyRequest &value){};
 #endif
+
 #ifdef USE_BLUETOOTH_PROXY
   virtual void on_bluetooth_set_connection_params_request(const BluetoothSetConnectionParamsRequest &value){};
 #endif

esphome/components/serial_proxy/__init__.py

@@ -0,0 +1,104 @@
+"""
+Serial Proxy component for ESPHome.
+
+WARNING: This component is EXPERIMENTAL. The API (both Python configuration
+and C++ interfaces) may change at any time without following the normal
+breaking changes policy. Use at your own risk.
+
+Once the API is considered stable, this warning will be removed.
+
+Provides a proxy to/from a serial interface on the ESPHome device, allowing
+Home Assistant to connect to the serial port and send/receive data to/from
+an arbitrary serial device.
+"""
+
+from dataclasses import dataclass
+
+from esphome import pins
+import esphome.codegen as cg
+from esphome.components import uart
+import esphome.config_validation as cv
+from esphome.const import CONF_ID, CONF_NAME
+from esphome.core import CORE, coroutine_with_priority
+from esphome.coroutine import CoroPriority
+
+CODEOWNERS = ["@kbx81"]
+DEPENDENCIES = ["api", "uart"]
+
+MULTI_CONF = True
+
+serial_proxy_ns = cg.esphome_ns.namespace("serial_proxy")
+SerialProxy = serial_proxy_ns.class_("SerialProxy", cg.Component, uart.UARTDevice)
+
+api_enums_ns = cg.esphome_ns.namespace("api").namespace("enums")
+SerialProxyPortType = api_enums_ns.enum("SerialProxyPortType")
+SERIAL_PROXY_PORT_TYPES = {
+    "TTL": SerialProxyPortType.SERIAL_PROXY_PORT_TYPE_TTL,
+    "RS232": SerialProxyPortType.SERIAL_PROXY_PORT_TYPE_RS232,
+    "RS485": SerialProxyPortType.SERIAL_PROXY_PORT_TYPE_RS485,
+}
+
+CONF_DTR_PIN = "dtr_pin"
+CONF_PORT_TYPE = "port_type"
+CONF_RTS_PIN = "rts_pin"
+
+DOMAIN = "serial_proxy"
+
+
+@dataclass
+class SerialProxyData:
+    count: int = 0
+
+
+def _get_data() -> SerialProxyData:
+    if DOMAIN not in CORE.data:
+        CORE.data[DOMAIN] = SerialProxyData()
+    return CORE.data[DOMAIN]
+
+
+CONFIG_SCHEMA = (
+    cv.Schema(
+        {
+            cv.GenerateID(): cv.declare_id(SerialProxy),
+            cv.Required(CONF_NAME): cv.string_strict,
+            cv.Required(CONF_PORT_TYPE): cv.enum(SERIAL_PROXY_PORT_TYPES, upper=True),
+            cv.Optional(CONF_RTS_PIN): pins.gpio_output_pin_schema,
+            cv.Optional(CONF_DTR_PIN): pins.gpio_output_pin_schema,
+        }
+    )
+    .extend(cv.COMPONENT_SCHEMA)
+    .extend(uart.UART_DEVICE_SCHEMA)
+)
+
+
+@coroutine_with_priority(CoroPriority.FINAL)
+async def _add_serial_proxy_count_define():
+    """Emit the SERIAL_PROXY_COUNT define once with the final instance count."""
+    count = _get_data().count
+    if count > 0:
+        cg.add_define("SERIAL_PROXY_COUNT", count)
+
+
+async def to_code(config):
+    var = cg.new_Pvariable(config[CONF_ID])
+    await cg.register_component(var, config)
+    await uart.register_uart_device(var, config)
+    cg.add(cg.App.register_serial_proxy(var))
+    cg.add(var.set_name(config[CONF_NAME]))
+    cg.add(var.set_port_type(config[CONF_PORT_TYPE]))
+    cg.add_define("USE_SERIAL_PROXY")
+
+    # Track instance count for the FINAL priority define
+    data = _get_data()
+    if data.count == 0:
+        # Schedule the count define job only once (on the first instance)
+        CORE.add_job(_add_serial_proxy_count_define)
+    data.count += 1
+
+    if CONF_RTS_PIN in config:
+        rts_pin = await cg.gpio_pin_expression(config[CONF_RTS_PIN])
+        cg.add(var.set_rts_pin(rts_pin))
+
+    if CONF_DTR_PIN in config:
+        dtr_pin = await cg.gpio_pin_expression(config[CONF_DTR_PIN])
+        cg.add(var.set_dtr_pin(dtr_pin))

esphome/components/serial_proxy/serial_proxy.cpp

@@ -0,0 +1,188 @@
+#include "serial_proxy.h"
+
+#ifdef USE_SERIAL_PROXY
+
+#include "esphome/core/log.h"
+#include "esphome/core/util.h"
+
+#ifdef USE_API
+#include "esphome/components/api/api_connection.h"
+#include "esphome/components/api/api_server.h"
+#endif
+
+namespace esphome::serial_proxy {
+
+static const char *const TAG = "serial_proxy";
+
+void SerialProxy::setup() {
+  // Set up modem control pins if configured
+  if (this->rts_pin_ != nullptr) {
+    this->rts_pin_->setup();
+    this->rts_pin_->digital_write(this->rts_state_);
+  }
+  if (this->dtr_pin_ != nullptr) {
+    this->dtr_pin_->setup();
+    this->dtr_pin_->digital_write(this->dtr_state_);
+  }
+#ifdef USE_API
+  // instance_index_ is fixed at registration time; pre-set it so loop() only needs to update data
+  this->outgoing_msg_.instance = this->instance_index_;
+#endif
+}
+
+void SerialProxy::loop() {
+#ifdef USE_API
+  // Detect subscriber disconnect
+  if (this->api_connection_ != nullptr && (this->api_connection_->is_marked_for_removal() ||
+                                           !this->api_connection_->is_connection_setup() || !api_is_connected())) {
+    ESP_LOGW(TAG, "Subscriber disconnected");
+    this->api_connection_ = nullptr;
+  }
+
+  if (this->api_connection_ == nullptr)
+    return;
+
+  // Read available data from UART and forward to subscribed client
+  size_t available = this->available();
+  if (available == 0)
+    return;
+
+  // Read in chunks up to SERIAL_PROXY_MAX_READ_SIZE
+  uint8_t buffer[SERIAL_PROXY_MAX_READ_SIZE];
+  size_t to_read = std::min(available, sizeof(buffer));
+
+  if (!this->read_array(buffer, to_read))
+    return;
+
+  this->outgoing_msg_.set_data(buffer, to_read);
+  this->api_connection_->send_serial_proxy_data(this->outgoing_msg_);
+#endif
+}
+
+void SerialProxy::dump_config() {
+  ESP_LOGCONFIG(TAG,
+                "Serial Proxy [%u]:\n"
+                "  Name: %s\n"
+                "  Port Type: %s\n"
+                "  RTS Pin: %s\n"
+                "  DTR Pin: %s",
+                this->instance_index_, this->name_ != nullptr ? this->name_ : "",
+                this->port_type_ == api::enums::SERIAL_PROXY_PORT_TYPE_RS485   ? "RS485"
+                : this->port_type_ == api::enums::SERIAL_PROXY_PORT_TYPE_RS232 ? "RS232"
+                                                                               : "TTL",
+                this->rts_pin_ != nullptr ? "configured" : "not configured",
+                this->dtr_pin_ != nullptr ? "configured" : "not configured");
+}
+
+void SerialProxy::configure(uint32_t baudrate, bool flow_control, uint8_t parity, uint8_t stop_bits,
+                            uint8_t data_size) {
+  ESP_LOGD(TAG, "Configuring serial proxy [%u]: baud=%u, flow_ctrl=%s, parity=%u, stop=%u, data=%u",
+           this->instance_index_, baudrate, YESNO(flow_control), parity, stop_bits, data_size);
+
+  auto *uart_comp = this->parent_;
+  if (uart_comp == nullptr) {
+    ESP_LOGE(TAG, "UART component not available");
+    return;
+  }
+
+  // Validate all parameters before applying any (values come from a remote client)
+  if (baudrate == 0) {
+    ESP_LOGW(TAG, "Invalid baud rate: 0");
+    return;
+  }
+  if (stop_bits < 1 || stop_bits > 2) {
+    ESP_LOGW(TAG, "Invalid stop bits: %u (must be 1 or 2)", stop_bits);
+    return;
+  }
+  if (data_size < 5 || data_size > 8) {
+    ESP_LOGW(TAG, "Invalid data bits: %u (must be 5-8)", data_size);
+    return;
+  }
+  if (parity > 2) {
+    ESP_LOGW(TAG, "Invalid parity: %u (must be 0-2)", parity);
+    return;
+  }
+
+  // Apply validated parameters
+  uart_comp->set_baud_rate(baudrate);
+  uart_comp->set_stop_bits(stop_bits);
+  uart_comp->set_data_bits(data_size);
+
+  // Map parity value to UARTParityOptions
+  static const uart::UARTParityOptions PARITY_MAP[] = {
+      uart::UART_CONFIG_PARITY_NONE,
+      uart::UART_CONFIG_PARITY_EVEN,
+      uart::UART_CONFIG_PARITY_ODD,
+  };
+  uart_comp->set_parity(PARITY_MAP[parity]);
+
+  // load_settings() is available on ESP8266 and ESP32 platforms
+#if defined(USE_ESP8266) || defined(USE_ESP32)
+  uart_comp->load_settings(true);
+#endif
+
+  if (flow_control) {
+    ESP_LOGW(TAG, "Hardware flow control requested but is not yet supported");
+  }
+}
+
+void SerialProxy::write_from_client(const uint8_t *data, size_t len) {
+  if (data == nullptr || len == 0)
+    return;
+  this->write_array(data, len);
+}
+
+void SerialProxy::set_modem_pins(uint32_t line_states) {
+  const bool rts = (line_states & SERIAL_PROXY_LINE_STATE_FLAG_RTS) != 0;
+  const bool dtr = (line_states & SERIAL_PROXY_LINE_STATE_FLAG_DTR) != 0;
+  ESP_LOGV(TAG, "Setting modem pins [%u]: RTS=%s, DTR=%s", this->instance_index_, ONOFF(rts), ONOFF(dtr));
+
+  if (this->rts_pin_ != nullptr) {
+    this->rts_state_ = rts;
+    this->rts_pin_->digital_write(rts);
+  }
+  if (this->dtr_pin_ != nullptr) {
+    this->dtr_state_ = dtr;
+    this->dtr_pin_->digital_write(dtr);
+  }
+}
+
+uint32_t SerialProxy::get_modem_pins() const {
+  return (this->rts_state_ ? SERIAL_PROXY_LINE_STATE_FLAG_RTS : 0u) |
+         (this->dtr_state_ ? SERIAL_PROXY_LINE_STATE_FLAG_DTR : 0u);
+}
+
+uart::FlushResult SerialProxy::flush_port() {
+  ESP_LOGV(TAG, "Flushing serial proxy [%u]", this->instance_index_);
+  return this->flush();
+}
+
+#ifdef USE_API
+void SerialProxy::serial_proxy_request(api::APIConnection *api_connection, api::enums::SerialProxyRequestType type) {
+  switch (type) {
+    case api::enums::SERIAL_PROXY_REQUEST_TYPE_SUBSCRIBE:
+      if (this->api_connection_ != nullptr) {
+        ESP_LOGE(TAG, "Only one API subscription is allowed at a time");
+        return;
+      }
+      this->api_connection_ = api_connection;
+      ESP_LOGV(TAG, "API connection subscribed to serial proxy [%u]", this->instance_index_);
+      break;
+    case api::enums::SERIAL_PROXY_REQUEST_TYPE_UNSUBSCRIBE:
+      if (this->api_connection_ != api_connection) {
+        ESP_LOGV(TAG, "API connection is not subscribed to serial proxy [%u]", this->instance_index_);
+        return;
+      }
+      this->api_connection_ = nullptr;
+      ESP_LOGV(TAG, "API connection unsubscribed from serial proxy [%u]", this->instance_index_);
+      break;
+    default:
+      ESP_LOGW(TAG, "Unknown serial proxy request type: %u", static_cast<uint32_t>(type));
+      break;
+  }
+}
+#endif
+
+}  // namespace esphome::serial_proxy
+
+#endif  // USE_SERIAL_PROXY

esphome/components/serial_proxy/serial_proxy.h

@@ -0,0 +1,129 @@
+#pragma once
+
+// WARNING: This component is EXPERIMENTAL. The API may change at any time
+// without following the normal breaking changes policy. Use at your own risk.
+// Once the API is considered stable, this warning will be removed.
+
+#include "esphome/core/defines.h"
+
+#ifdef USE_SERIAL_PROXY
+
+#include "esphome/core/component.h"
+#include "esphome/core/hal.h"
+#include "esphome/components/uart/uart.h"
+
+// Include api_pb2.h only when the API is enabled. The full include is needed
+// to hold SerialProxyDataReceived by value as a pre-allocated member.
+// Guarding prevents pulling conflicting Zephyr logging macro names into
+// translation units that include this header without USE_API defined.
+#ifdef USE_API
+#include "esphome/components/api/api_pb2.h"
+#endif
+
+// Forward-declare types needed outside the USE_API guard.
+namespace esphome::api {
+class APIConnection;
+namespace enums {
+enum SerialProxyPortType : uint32_t;
+enum SerialProxyRequestType : uint32_t;
+}  // namespace enums
+}  // namespace esphome::api
+
+namespace esphome::serial_proxy {
+
+/// Bit flags for the line_states field exchanged with API clients.
+/// Bit positions are stable API — new signals must use the next available bit.
+enum SerialProxyLineStateFlag : uint32_t {
+  SERIAL_PROXY_LINE_STATE_FLAG_RTS = 1 << 0,  ///< RTS (Request To Send)
+  SERIAL_PROXY_LINE_STATE_FLAG_DTR = 1 << 1,  ///< DTR (Data Terminal Ready)
+};
+
+/// Maximum bytes to read from UART in a single loop iteration
+inline constexpr size_t SERIAL_PROXY_MAX_READ_SIZE = 256;
+
+class SerialProxy : public uart::UARTDevice, public Component {
+ public:
+  void setup() override;
+  void loop() override;
+  void dump_config() override;
+  float get_setup_priority() const override { return setup_priority::AFTER_CONNECTION; }
+
+  /// Get the instance index (position in Application's serial_proxies_ vector)
+  uint32_t get_instance_index() const { return this->instance_index_; }
+
+  /// Set the instance index (called by Application::register_serial_proxy)
+  void set_instance_index(uint32_t index) { this->instance_index_ = index; }
+
+  /// Set the human-readable port name (from YAML configuration)
+  void set_name(const char *name) { this->name_ = name; }
+
+  /// Get the human-readable port name
+  const char *get_name() const { return this->name_; }
+
+  /// Set the port type (from YAML configuration)
+  void set_port_type(api::enums::SerialProxyPortType port_type) { this->port_type_ = port_type; }
+
+  /// Get the port type
+  api::enums::SerialProxyPortType get_port_type() const { return this->port_type_; }
+
+  /// Configure UART parameters and apply them
+  /// @param baudrate Baud rate in bits per second
+  /// @param flow_control True to enable hardware flow control
+  /// @param parity Parity setting (0=none, 1=even, 2=odd)
+  /// @param stop_bits Number of stop bits (1 or 2)
+  /// @param data_size Number of data bits (5-8)
+  void configure(uint32_t baudrate, bool flow_control, uint8_t parity, uint8_t stop_bits, uint8_t data_size);
+
+  /// Handle a subscribe/unsubscribe request from an API client
+  void serial_proxy_request(api::APIConnection *api_connection, api::enums::SerialProxyRequestType type);
+
+  /// Write data received from an API client to the serial device
+  /// @param data Pointer to data buffer
+  /// @param len Number of bytes to write
+  void write_from_client(const uint8_t *data, size_t len);
+
+  /// Set modem pin states from a bitmask of SerialProxyLineStateFlag values
+  void set_modem_pins(uint32_t line_states);
+
+  /// Get current modem pin states as a bitmask of SerialProxyLineStateFlag values
+  uint32_t get_modem_pins() const;
+
+  /// Flush the serial port (block until all TX data is sent)
+  uart::FlushResult flush_port();
+
+  /// Set the RTS GPIO pin (from YAML configuration)
+  void set_rts_pin(GPIOPin *pin) { this->rts_pin_ = pin; }
+
+  /// Set the DTR GPIO pin (from YAML configuration)
+  void set_dtr_pin(GPIOPin *pin) { this->dtr_pin_ = pin; }
+
+ protected:
+  /// Instance index for identifying this proxy in API messages
+  uint32_t instance_index_{0};
+
+  /// Subscribed API client (only one allowed at a time)
+  api::APIConnection *api_connection_{nullptr};
+
+#ifdef USE_API
+  /// Pre-allocated outgoing message; instance field is set once in setup()
+  api::SerialProxyDataReceived outgoing_msg_;
+#endif
+
+  /// Human-readable port name (points to a string literal in flash)
+  const char *name_{nullptr};
+
+  /// Port type
+  api::enums::SerialProxyPortType port_type_{};
+
+  /// Optional GPIO pins for modem control
+  GPIOPin *rts_pin_{nullptr};
+  GPIOPin *dtr_pin_{nullptr};
+
+  /// Current modem pin states
+  bool rts_state_{false};
+  bool dtr_state_{false};
+};
+
+}  // namespace esphome::serial_proxy
+
+#endif  // USE_SERIAL_PROXY

esphome/core/application.h

@@ -102,6 +102,9 @@ void socket_wake();  // NOLINT(readability-redundant-declaration)
 #ifdef USE_INFRARED
 #include "esphome/components/infrared/infrared.h"
 #endif
+#ifdef USE_SERIAL_PROXY
+#include "esphome/components/serial_proxy/serial_proxy.h"
+#endif
 #ifdef USE_EVENT
 #include "esphome/components/event/event.h"
 #endif
@@ -267,6 +270,13 @@ class Application {
   void register_infrared(infrared::Infrared *infrared) { this->infrareds_.push_back(infrared); }
 #endif
 
+#ifdef USE_SERIAL_PROXY
+  void register_serial_proxy(serial_proxy::SerialProxy *proxy) {
+    proxy->set_instance_index(this->serial_proxies_.size());
+    this->serial_proxies_.push_back(proxy);
+  }
+#endif
+
 #ifdef USE_EVENT
   void register_event(event::Event *event) { this->events_.push_back(event); }
 #endif
@@ -498,6 +508,10 @@ class Application {
   GET_ENTITY_METHOD(infrared::Infrared, infrared, infrareds)
 #endif
 
+#ifdef USE_SERIAL_PROXY
+  auto &get_serial_proxies() const { return this->serial_proxies_; }
+#endif
+
 #ifdef USE_EVENT
   auto &get_events() const { return this->events_; }
   GET_ENTITY_METHOD(event::Event, event, events)
@@ -747,6 +761,9 @@ class Application {
 #ifdef USE_INFRARED
   StaticVector<infrared::Infrared *, ESPHOME_ENTITY_INFRARED_COUNT> infrareds_{};
 #endif
+#ifdef USE_SERIAL_PROXY
+  StaticVector<serial_proxy::SerialProxy *, SERIAL_PROXY_COUNT> serial_proxies_{};
+#endif
 #ifdef USE_UPDATE
   StaticVector<update::UpdateEntity *, ESPHOME_ENTITY_UPDATE_COUNT> updates_{};
 #endif

esphome/core/defines.h

@@ -107,6 +107,7 @@
 #define MDNS_SERVICE_COUNT 3
 #define USE_MDNS_DYNAMIC_TXT
 #define MDNS_DYNAMIC_TXT_COUNT 2
+#define SERIAL_PROXY_COUNT 2
 #define SNTP_SERVER_COUNT 3
 #define USE_MEDIA_PLAYER
 #define USE_MEDIA_SOURCE
@@ -119,6 +120,7 @@
 #define USE_SELECT
 #define USE_SENSOR
 #define USE_SENSOR_FILTER
+#define USE_SERIAL_PROXY
 #define USE_SETUP_PRIORITY_OVERRIDE
 #define USE_STATUS_LED
 #define USE_STATUS_SENSOR

tests/components/serial_proxy/common.yaml

@@ -0,0 +1,10 @@
+wifi:
+  ssid: MySSID
+  password: password1
+
+api:
+
+serial_proxy:
+  - id: serial_proxy_1
+    name: Test Serial Port
+    port_type: RS232

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

@@ -0,0 +1,8 @@
+substitutions:
+  tx_pin: GPIO4
+  rx_pin: GPIO5
+
+packages:
+  uart: !include ../../test_build_components/common/uart/esp32-idf.yaml
+
+<<: !include common.yaml

tests/components/serial_proxy/test.esp8266-ard.yaml

@@ -0,0 +1,8 @@
+substitutions:
+  tx_pin: GPIO0
+  rx_pin: GPIO2
+
+packages:
+  uart: !include ../../test_build_components/common/uart/esp8266-ard.yaml
+
+<<: !include common.yaml

tests/components/serial_proxy/test.rp2040-ard.yaml

@@ -0,0 +1,8 @@
+substitutions:
+  tx_pin: GPIO4
+  rx_pin: GPIO5
+
+packages:
+  uart: !include ../../test_build_components/common/uart/rp2040-ard.yaml
+
+<<: !include common.yaml