serial_proxy.cpp

Go to the documentation of this file.

#include "serial_proxy.h"
 
#ifdef USE_SERIAL_PROXY
 
#include "esphome/core/application.h"
#include "esphome/core/log.h"
 
#include <algorithm>
#include <cinttypes>
#include "esphome/core/util.h"
 
#ifdef USE_API
#include "esphome/components/api/api_connection.h"
#include "esphome/components/api/api_server.h"
#endif
 
#ifdef USE_SERIAL_PROXY_USB_IDENTITY
#include "esphome/components/usb_uart/usb_uart.h"
#endif
 
#ifdef USE_SERIAL_PROXY_HOST_UART
#include "esphome/components/uart/uart_component_host.h"
#endif
 
namespace esphome::serial_proxy {
 
ESPHOME_LOG_TAG(TAG, "serial_proxy");
 
uint32_t SerialProxy::stall_loop_time = 0;
uint32_t SerialProxy::stall_spent_ms = 0;
 
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
#ifdef USE_SERIAL_PROXY_USB_IDENTITY
  if (this->usb_channel_ != nullptr) {
    this->usb_channel_->get_parent()->add_on_connection_callback(
        [this](bool connected) { this->on_usb_connection_changed_(connected); });
  }
#endif
#ifdef USE_SERIAL_PROXY_TAP
  // A tap sets itself up before this runs (its setup priority is higher), so it may
  // already be waiting on the port -- a boot-time handshake with the device, say. Leaving
  // the loop enabled is what lets that finish; without it the tap would stall until a
  // client happened to subscribe.
  if (this->tap_ != nullptr && this->tap_->tap_needs_port()) {
    return;
  }
#endif
  // No subscriber at startup; disable loop until a client subscribes
  this->disable_loop();
}
 
#ifdef USE_SERIAL_PROXY_TAP
void SerialProxy::reset_mode_() {
  // The mode belongs to a session, not to the port. Carrying a departed client's choice
  // over to the next one would inject protocol bytes into a stream that never asked for
  // them -- a firmware upload, or any client built before this request existed and so
  // unable to turn it off. Guessing RAW is the safe direction: a client that wanted
  // protocol handling and did not ask for it merely sends its own acknowledgements.
  if (this->mode_ == api::enums::SERIAL_PROXY_MODE_RAW) {
    return;
  }
  ESP_LOGD(TAG, "Session ended, returning serial proxy [%" PRIu32 "] to RAW mode", this->instance_index_);
  this->mode_ = api::enums::SERIAL_PROXY_MODE_RAW;
}
#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;
    this->reset_mode_();
  }
 
  // With no subscriber there is normally nothing to do, but a tap may still need the port
  // read -- it does its protocol work precisely while nobody else is listening.
  if (this->api_connection_ == nullptr) [[unlikely]] {
#ifdef USE_SERIAL_PROXY_TAP
    if (this->tap_ == nullptr || !this->tap_->tap_needs_port()) {
      this->disable_loop();
      return;
    }
#else
    this->disable_loop();
    return;
#endif
  }
 
  // Read available data from UART and forward to subscribed client
  size_t available = this->available();
  if (available == 0)
    return;
 
  this->read_and_send_(available);
#endif
}
 
#ifdef USE_API
void __attribute__((noinline)) SerialProxy::read_and_send_(size_t available) {
  // 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;
 
#ifdef USE_SERIAL_PROXY_TAP
  // Before forwarding, so a tap that answers the device (an acknowledgement, say) is not
  // waiting on the network round trip to a subscriber that may not even exist.
  if (this->tap_observing_()) {
    this->tap_->on_device_rx(buffer, to_read);
  }
#endif
 
  if (this->api_connection_ == nullptr) {
    return;
  }
  this->outgoing_msg_.set_data(buffer, to_read);
  this->api_connection_->send_serial_proxy_data(this->outgoing_msg_);
}
#endif
 
#ifdef USE_SERIAL_PROXY_TAP
 
bool SerialProxy::tap_observing_() const {
  if (this->tap_ == nullptr) {
    return false;
  }
  // With no subscriber, a tap doing its own protocol work (the boot-time handshake with
  // the device, say) is served regardless of mode -- nobody has chosen one yet. Once a
  // subscriber holds the port, the mode alone decides, so RAW stays inert.
  if (this->api_connection_ == nullptr && this->tap_->tap_needs_port()) {
    return true;
  }
  // Otherwise the mode decides. RAW must be inert: a client that flips to RAW before
  // flashing firmware is entitled to a byte pipe with nothing injecting protocol bytes
  // into it, and "the tap turned out not to recognise the stream" is not good enough.
  return this->mode_ == api::enums::SERIAL_PROXY_MODE_PROTOCOL;
}
 
void SerialProxy::tap_pump() {
#ifdef USE_API
  // Nothing would consume the bytes; leave them in the FIFO
  if (!this->tap_observing_() && this->api_connection_ == nullptr) {
    return;
  }
  const size_t available = this->available();
  if (available > 0) {
    this->read_and_send_(available);
  }
#endif
}
#endif
 
void SerialProxy::dump_config() {
  ESP_LOGCONFIG(TAG,
                "Serial Proxy [%" PRIu32 "]:\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        ? LOG_STR_LITERAL("RS485")
                : this->port_type_ == api::enums::SERIAL_PROXY_PORT_TYPE_RS232      ? LOG_STR_LITERAL("RS232")
                : this->port_type_ == api::enums::SERIAL_PROXY_PORT_TYPE_USB_SERIAL ? LOG_STR_LITERAL("USB_SERIAL")
                                                                                    : LOG_STR_LITERAL("TTL"),
                this->rts_pin_ != nullptr ? LOG_STR_LITERAL("configured") : LOG_STR_LITERAL("not configured"),
                this->dtr_pin_ != nullptr ? LOG_STR_LITERAL("configured") : LOG_STR_LITERAL("not configured"));
}
 
SerialProxyResult SerialProxy::configure(api::APIConnection *api_connection, uint32_t baudrate, bool flow_control,
                                         uint8_t parity, uint8_t stop_bits, uint8_t data_size) {
#ifdef USE_API
  if (!this->is_subscriber_(api_connection)) {
    ESP_LOGW(TAG, "Ignoring configure request from client without port subscription [%" PRIu32 "]",
             this->instance_index_);
    return SerialProxyResult::SERIAL_PROXY_RESULT_PORT_IN_USE;
  }
#endif
  ESP_LOGD(TAG,
           "Configuring serial proxy [%" PRIu32 "]: baud=%" PRIu32 ", flow_ctrl=%s, parity=%" PRIu8 ", stop=%" PRIu8
           ", data=%" PRIu8,
           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 SerialProxyResult::SERIAL_PROXY_RESULT_ERROR;
  }
 
  // Validate all parameters before applying any (values come from a remote client)
  if (baudrate == 0) {
    ESP_LOGW(TAG, "Invalid baud rate: 0");
    return SerialProxyResult::SERIAL_PROXY_RESULT_INVALID_ARGUMENT;
  }
  if (stop_bits < 1 || stop_bits > 2) {
    ESP_LOGW(TAG, "Invalid stop bits: %u (must be 1 or 2)", stop_bits);
    return SerialProxyResult::SERIAL_PROXY_RESULT_INVALID_ARGUMENT;
  }
  if (data_size < 5 || data_size > 8) {
    ESP_LOGW(TAG, "Invalid data bits: %u (must be 5-8)", data_size);
    return SerialProxyResult::SERIAL_PROXY_RESULT_INVALID_ARGUMENT;
  }
  if (parity > 2) {
    ESP_LOGW(TAG, "Invalid parity: %u (must be 0-2)", parity);
    return SerialProxyResult::SERIAL_PROXY_RESULT_INVALID_ARGUMENT;
  }
  if (flow_control) {
    ESP_LOGW(TAG, "Hardware flow control requested but is not yet supported");
    return SerialProxyResult::SERIAL_PROXY_RESULT_NOT_SUPPORTED;
  }
 
  // Skip a no-op reconfigure. Clients routinely re-send identical settings on every
  // port open, and on a USB UART each apply is a CDC SET_LINE_CODING control transfer.
  // Some bridges watch line-coding changes as a signalling channel (a magic baud
  // sequence to enter a bootloader, say), so redundant applies are not harmless.
  static const uart::UARTParityOptions PARITY_MAP[] = {
      uart::UART_CONFIG_PARITY_NONE,
      uart::UART_CONFIG_PARITY_EVEN,
      uart::UART_CONFIG_PARITY_ODD,
  };
  if (uart_comp->get_baud_rate() == baudrate && uart_comp->get_stop_bits() == stop_bits &&
      uart_comp->get_data_bits() == data_size && uart_comp->get_parity() == PARITY_MAP[parity]) {
    ESP_LOGV(TAG, "Settings unchanged, skipping reconfigure [%" PRIu32 "]", this->instance_index_);
    return SerialProxyResult::SERIAL_PROXY_RESULT_OK;
  }
 
  // Apply validated parameters
  uart_comp->set_baud_rate(baudrate);
  uart_comp->set_stop_bits(stop_bits);
  uart_comp->set_data_bits(data_size);
 
  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
  return SerialProxyResult::SERIAL_PROXY_RESULT_OK;
}
 
SerialProxyResult SerialProxy::set_mode_from_client(api::APIConnection *api_connection,
                                                    api::enums::SerialProxyMode mode) {
#ifdef USE_API
  // Only the live subscriber may change the mode, so the mode cannot outlive a session
  if (!this->is_subscriber_(api_connection)) {
    ESP_LOGW(TAG, "Ignoring mode request from client without port subscription [%" PRIu32 "]", this->instance_index_);
    return SerialProxyResult::SERIAL_PROXY_RESULT_PORT_IN_USE;
  }
#endif
  // Values come from a remote client
  if (mode != api::enums::SERIAL_PROXY_MODE_RAW && mode != api::enums::SERIAL_PROXY_MODE_PROTOCOL) {
    ESP_LOGW(TAG, "Invalid mode: %" PRIu32, static_cast<uint32_t>(mode));
    return SerialProxyResult::SERIAL_PROXY_RESULT_INVALID_ARGUMENT;
  }
  // PROTOCOL on a port with no tap would be a silent no-op; refuse so the client knows
#ifdef USE_SERIAL_PROXY_TAP
  const bool has_tap = this->tap_ != nullptr;
#else
  const bool has_tap = false;
#endif
  if (mode == api::enums::SERIAL_PROXY_MODE_PROTOCOL && !has_tap) {
    ESP_LOGW(TAG, "No tap on serial proxy [%" PRIu32 "]; PROTOCOL mode unavailable", this->instance_index_);
    return SerialProxyResult::SERIAL_PROXY_RESULT_NOT_SUPPORTED;
  }
  ESP_LOGD(TAG, "Serial proxy [%" PRIu32 "] mode set to %s", this->instance_index_,
           mode == api::enums::SERIAL_PROXY_MODE_PROTOCOL ? LOG_STR_LITERAL("PROTOCOL") : LOG_STR_LITERAL("RAW"));
#ifdef USE_SERIAL_PROXY_TAP
  const bool entering_protocol_mode =
      this->mode_ != api::enums::SERIAL_PROXY_MODE_PROTOCOL && mode == api::enums::SERIAL_PROXY_MODE_PROTOCOL;
  const bool leaving_protocol_mode =
      this->mode_ != api::enums::SERIAL_PROXY_MODE_RAW && mode == api::enums::SERIAL_PROXY_MODE_RAW;
  this->mode_ = mode;
 
  if (entering_protocol_mode && this->tap_ != nullptr) {
    this->tap_->on_protocol_enabled();
  }
 
  // Only for an explicit client request, not for reset_mode_() at the end of a session:
  // an ordinary disconnect says nothing about the device, whereas a client deliberately
  // asking for raw bytes usually precedes changing what the device is.
  if (leaving_protocol_mode && this->tap_ != nullptr) {
    this->tap_->on_protocol_disabled();
  }
#endif
  return SerialProxyResult::SERIAL_PROXY_RESULT_OK;
}
 
void SerialProxy::write_from_client(api::APIConnection *api_connection, const uint8_t *data, size_t len) {
#ifdef USE_API
  // Bytes from anyone but the live subscriber would interleave with the subscriber's
  // traffic -- or with an active tap's -- on the wire
  if (!this->is_subscriber_(api_connection)) {
    if (this->api_connection_ != nullptr) {
      ESP_LOGW(TAG, "Ignoring write from client that does not hold serial proxy [%" PRIu32 "]", this->instance_index_);
    } else {
      // A legacy client streaming writes without subscribing would flood WARN, one per
      // request; writes are the only high-rate, unacknowledged operation, so keep this
      // visible without drowning the log
      ESP_LOGV(TAG, "Ignoring write from client without port subscription [%" PRIu32 "]", this->instance_index_);
    }
    return;
  }
#endif
  if (data == nullptr || len == 0)
    return;
  // Whatever the driver cannot buffer stalls the main loop for its wire time. At high baud
  // rates that is brief and losing nothing is worth it; at low ones it would trip the
  // watchdog, so cap the stall and drop the rest. The cap covers the whole loop pass:
  // several writes can arrive in one, and each alone might stay under it.
  const size_t free = this->parent_->available_for_write();
  bool trimmed = false;
  if (len > free) {
    const uint32_t loop_time = App.get_loop_component_start_time();
    if (loop_time != stall_loop_time) {
      stall_loop_time = loop_time;
      stall_spent_ms = 0;
    }
    const uint32_t stall_ms = this->wire_time_ms_(len - free);
    trimmed = stall_spent_ms + stall_ms > SERIAL_PROXY_MAX_WRITE_STALL_MS;
    if (trimmed && !this->trim_warned_) {
      ESP_LOGW(TAG,
               "TX buffer full on serial proxy [%" PRIu32 "]: dropping %zu of %zu bytes (would stall %" PRIu32
               " ms at %" PRIu32 " baud); raise the UART tx_buffer_size or pace writes",
               this->instance_index_, len - free, len, stall_ms, this->parent_->get_baud_rate());
    }
    if (trimmed) {
      len = free;
    } else {
      stall_spent_ms += stall_ms;
    }
  }
  this->trim_warned_ = trimmed;
  if (len == 0)
    return;
  this->write_array(data, len);
 
#ifdef USE_SERIAL_PROXY_TAP
  // After the write, so the tap observes the same ordering the device does
  if (this->tap_observing_()) {
    this->tap_->on_client_tx(data, len);
  }
#endif
}
 
uint32_t SerialProxy::wire_time_ms_(size_t bytes) const {
  const uint32_t bits_per_byte = 1 + this->parent_->get_data_bits() + this->parent_->get_stop_bits() +
                                 (this->parent_->get_parity() != uart::UART_CONFIG_PARITY_NONE ? 1 : 0);
  return static_cast<uint64_t>(bytes) * bits_per_byte * 1000 / std::max<uint32_t>(this->parent_->get_baud_rate(), 1);
}
 
SerialProxyResult SerialProxy::set_modem_pins(api::APIConnection *api_connection, uint32_t line_states) {
#ifdef USE_API
  if (!this->is_subscriber_(api_connection)) {
    ESP_LOGW(TAG, "Ignoring modem pin request from client without port subscription [%" PRIu32 "]",
             this->instance_index_);
    return SerialProxyResult::SERIAL_PROXY_RESULT_PORT_IN_USE;
  }
#endif
  // Asserting a pin that is not configured must fail so the client learns the signal never
  // reached the wire; deasserting an absent pin is harmless and stays allowed. Clients can
  // avoid this by masking against SerialProxyInfo.configured_line_states.
  if ((line_states & ~this->get_configured_modem_pins()) != 0) {
    ESP_LOGW(TAG, "Requested modem pin not configured on serial proxy [%" PRIu32 "]", this->instance_index_);
    return SerialProxyResult::SERIAL_PROXY_RESULT_NOT_SUPPORTED;
  }
  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 [%" PRIu32 "]: RTS=%s, DTR=%s", this->instance_index_, ONOFF(rts), ONOFF(dtr));
 
  // The UART goes first, so a failure leaves every line as it was. A line with a GPIO pin keeps
  // the UART's current state; with both on GPIO there is nothing to send
  bool applied = true;
  if (this->rts_pin_ == nullptr || this->dtr_pin_ == nullptr) {
    this->with_modem_uart_([this, dtr, rts, &applied](auto *uart) {
      applied = uart->set_modem_control(this->dtr_pin_ != nullptr ? uart->get_dtr() : dtr,
                                        this->rts_pin_ != nullptr ? uart->get_rts() : rts);
    });
  }
  if (!applied) {
    ESP_LOGW(TAG, "Modem pins did not reach the UART on serial proxy [%" PRIu32 "]", this->instance_index_);
    return SerialProxyResult::SERIAL_PROXY_RESULT_ERROR;
  }
  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);
  }
  return SerialProxyResult::SERIAL_PROXY_RESULT_OK;
}
 
#ifdef USE_API
void SerialProxy::send_identity(api::APIConnection *api_connection) {
  IdentityScratch scratch;
  api::SerialProxyIdentity msg{};
  this->fill_identity_(scratch, msg);
  api_connection->send_serial_proxy_identity(msg);
}
 
void SerialProxy::fill_identity_([[maybe_unused]] IdentityScratch &scratch, api::SerialProxyIdentity &msg) const {
  msg.instance = this->instance_index_;
#ifdef USE_SERIAL_PROXY_USB_IDENTITY
  // The define is global, so a hardware UART port in the same config also gets here
  if (this->usb_channel_ != nullptr) {
    msg.source = api::enums::SERIAL_PROXY_IDENTITY_SOURCE_USB;
    // Covers a removed device, a channel the device has no CDC function for and a failed channel setup
    if (!this->usb_channel_->is_connected()) {
      return;
    }
    auto *client = this->usb_channel_->get_parent();
    msg.flags = api::enums::SERIAL_PROXY_IDENTITY_FLAG_CONNECTED;
    if (!client->get_device_info(scratch)) {
      msg.flags |= api::enums::SERIAL_PROXY_IDENTITY_FLAG_ERROR;
      return;
    }
    msg.usb.vendor_id = scratch.vendor_id;
    msg.usb.product_id = scratch.product_id;
    msg.usb.bcd_device = scratch.bcd_device;
    msg.usb.interface_number = this->usb_channel_->get_interface_number();
    msg.usb.interface_class = this->usb_channel_->get_interface_class();
    msg.usb.port_number = this->usb_channel_->get_port_number();
    msg.manufacturer = StringRef(scratch.manufacturer);
    msg.product = StringRef(scratch.product);
    msg.serial_number = StringRef(scratch.serial_number);
    return;
  }
#endif
  // Zero-initialized message: source NONE, no flags
}
#endif
 
#ifdef USE_SERIAL_PROXY_USB_IDENTITY
void SerialProxy::on_usb_connection_changed_(bool connected) {
  ESP_LOGD(TAG, "USB device %s serial proxy [%" PRIu32 "]",
           connected ? LOG_STR_LITERAL("attached to") : LOG_STR_LITERAL("removed from"), this->instance_index_);
#ifdef USE_SERIAL_PROXY_TAP
  // Before telling clients, so a tap never acknowledges a frame from the old device after
  // a client has been told it is gone. The subscriber and the mode stay: both belong to
  // the client's session, and only the client knows whether that session is over.
  if (!connected && this->tap_ != nullptr) {
    this->tap_->on_device_disconnected();
  }
#endif
#ifdef USE_API
  if (api::global_api_server == nullptr) {
    return;
  }
  IdentityScratch scratch;
  api::SerialProxyIdentity msg{};
  this->fill_identity_(scratch, msg);
  api::global_api_server->send_serial_proxy_identity(msg);
#endif
}
#endif
 
uint32_t SerialProxy::get_modem_pins() const {
  bool rts = this->rts_state_;
  bool dtr = this->dtr_state_;
  this->with_modem_uart_([this, &rts, &dtr](auto *uart) {
    if (this->rts_pin_ == nullptr)
      rts = uart->get_rts();
    if (this->dtr_pin_ == nullptr)
      dtr = uart->get_dtr();
  });
  return (rts ? static_cast<uint32_t>(SERIAL_PROXY_LINE_STATE_FLAG_RTS) : 0u) |
         (dtr ? static_cast<uint32_t>(SERIAL_PROXY_LINE_STATE_FLAG_DTR) : 0u);
}
 
SerialProxyResult SerialProxy::flush_port(api::APIConnection *api_connection) {
#ifdef USE_API
  // Flushing stalls the port, so it gets the same ownership check as writes
  if (!this->is_subscriber_(api_connection)) {
    ESP_LOGW(TAG, "Ignoring flush from client without port subscription [%" PRIu32 "]", this->instance_index_);
    return SerialProxyResult::SERIAL_PROXY_RESULT_PORT_IN_USE;
  }
#endif
  ESP_LOGV(TAG, "Flushing serial proxy [%" PRIu32 "]", this->instance_index_);
  switch (this->flush()) {
    case uart::UARTFlushResult::UART_FLUSH_RESULT_SUCCESS:
      return SerialProxyResult::SERIAL_PROXY_RESULT_OK;
    case uart::UARTFlushResult::UART_FLUSH_RESULT_ASSUMED_SUCCESS:
      return SerialProxyResult::SERIAL_PROXY_RESULT_ASSUMED_SUCCESS;
    case uart::UARTFlushResult::UART_FLUSH_RESULT_TIMEOUT:
      return SerialProxyResult::SERIAL_PROXY_RESULT_TIMEOUT;
    case uart::UARTFlushResult::UART_FLUSH_RESULT_FAILED:
      return SerialProxyResult::SERIAL_PROXY_RESULT_ERROR;
  }
  return SerialProxyResult::SERIAL_PROXY_RESULT_ERROR;  // Unreachable; all enum values handled above
}
 
#ifdef USE_API
SerialProxyResult 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_ == api_connection) {
        ESP_LOGV(TAG, "API connection is already subscribed to serial proxy [%" PRIu32 "]", this->instance_index_);
        return SerialProxyResult::SERIAL_PROXY_RESULT_OK;
      }
      if (this->api_connection_ != nullptr) {
        // A living subscriber keeps exclusive access. Its connection may be dead without
        // loop() having noticed yet (e.g. the client crashed and reconnected quickly);
        // in that case let the new client take over instead of locking it out.
        if (this->api_connection_->is_connection_setup()) {
          ESP_LOGE(TAG, "Only one API subscription is allowed at a time");
          return SerialProxyResult::SERIAL_PROXY_RESULT_PORT_IN_USE;
        }
        ESP_LOGW(TAG, "Previous subscriber disconnected; taking over subscription");
        // End the dead client's session before starting the new one, so its mode
        // cannot leak into a session that never asked for it
        this->api_connection_ = nullptr;
        this->reset_mode_();
      }
      this->api_connection_ = api_connection;
      this->enable_loop();
      ESP_LOGV(TAG, "API connection subscribed to serial proxy [%" PRIu32 "]", this->instance_index_);
      return SerialProxyResult::SERIAL_PROXY_RESULT_OK;
    case api::enums::SERIAL_PROXY_REQUEST_TYPE_UNSUBSCRIBE:
      // Unsubscribe is idempotent: not being subscribed is not an error
      if (this->api_connection_ != api_connection) {
        ESP_LOGV(TAG, "API connection is not subscribed to serial proxy [%" PRIu32 "]", this->instance_index_);
        return SerialProxyResult::SERIAL_PROXY_RESULT_OK;
      }
      this->api_connection_ = nullptr;
      this->reset_mode_();
#ifdef USE_SERIAL_PROXY_TAP
      // Keep the loop alive for a tap that still needs the port (mirrors loop())
      if (this->tap_ == nullptr || !this->tap_->tap_needs_port()) {
        this->disable_loop();
      }
#else
      this->disable_loop();
#endif
      ESP_LOGV(TAG, "API connection unsubscribed from serial proxy [%" PRIu32 "]", this->instance_index_);
      return SerialProxyResult::SERIAL_PROXY_RESULT_OK;
    default:
      ESP_LOGW(TAG, "Unknown serial proxy request type: %" PRIu32, static_cast<uint32_t>(type));
      return SerialProxyResult::SERIAL_PROXY_RESULT_NOT_SUPPORTED;
  }
}
#endif
 
}  // namespace esphome::serial_proxy
 
#endif  // USE_SERIAL_PROXY