[packet_interface] Reject a layer type registered after the schemas are built

Such a type would be missing from the link schema, and selecting it would
fail with an unrelated error.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

CODEOWNERS

@@ -457,6 +457,8 @@ esphome/components/openthread/* @mrene
 esphome/components/opt3001/* @ccutrer
 esphome/components/ota/* @esphome/core
 esphome/components/output/* @esphome/core
+esphome/components/packet_interface/* @clydebarrow
+esphome/components/packet_interface/packet_transport/* @clydebarrow
 esphome/components/packet_transport/* @clydebarrow
 esphome/components/pca6416a/* @Mat931
 esphome/components/pca9505/* @ajfriesen @ssieb
@@ -673,10 +675,12 @@ esphome/components/tuya/water_heater/* @iago-veiga
 esphome/components/uart/* @esphome/core
 esphome/components/uart/button/* @ssieb
 esphome/components/uart/event/* @eoasmxd
+esphome/components/uart/packet_interface/* @clydebarrow
 esphome/components/uart/packet_transport/* @clydebarrow
 esphome/components/uart_mux/* @kbx81
 esphome/components/uart_tcp/* @Bascht74
 esphome/components/udp/* @clydebarrow
+esphome/components/udp/packet_interface/* @clydebarrow
 esphome/components/ufire_ec/* @pvizeli
 esphome/components/ufire_ise/* @pvizeli
 esphome/components/ufm01/* @ljungqvist

esphome/components/packet_interface/__init__.py

@@ -0,0 +1,66 @@
+import importlib
+import pkgutil
+from typing import Any
+
+import esphome.codegen as cg
+from esphome.components.const import CONF_MAX_PACKET_SIZE
+import esphome.config_validation as cv
+from esphome.const import CONF_ID
+from esphome.cpp_generator import MockObj, MockObjClass
+from esphome.types import ConfigType
+
+from . import layers
+from .layers import PacketInterface, build_stack, packet_interface_ns, stack_schema
+
+CODEOWNERS = ["@clydebarrow"]
+DOMAIN = "packet_interface"
+IS_PLATFORM_COMPONENT = True
+
+CONF_PACKET_INTERFACE = "packet_interface"
+
+# Each module in layers registers a layer type; import them all before building the schemas from the registry
+for module_info in pkgutil.iter_modules(layers.__path__):
+    importlib.import_module(f".layers.{module_info.name}", package=__package__)
+
+LINK_LAYER_SCHEMAS = stack_schema()
+
+__all__ = [
+    "CONF_MAX_PACKET_SIZE",
+    "CONF_PACKET_INTERFACE",
+    "PacketInterface",
+    "new_packet_interface",
+    "packet_interface_ns",
+    "packet_interface_schema",
+]
+
+
+def packet_interface_schema(
+    class_: MockObjClass,
+    default_max_packet_size: int,
+    max_packet_size_limit: int = 4096,
+) -> cv.Schema:
+    """Schema for a link platform, with the layers that can be stacked on it."""
+    return cv.Schema(
+        {
+            cv.GenerateID(): cv.declare_id(class_),
+            cv.Optional(
+                CONF_MAX_PACKET_SIZE, default=default_max_packet_size
+            ): cv.int_range(16, max_packet_size_limit),
+            **LINK_LAYER_SCHEMAS,
+        }
+    ).extend(cv.COMPONENT_SCHEMA)
+
+
+async def new_packet_interface(config: ConfigType, *args: Any) -> MockObj:
+    """Create the link layer and the layers configured on it, from the bottom up.
+
+    The link's constructor takes its maximum packet size, usually as a std::span over a buffer that code generation
+    sized from the configuration, so the two cannot differ.
+
+    Returns the link layer; applications reach the top layer with PacketInterface::top().
+    """
+    var = cg.new_Pvariable(config[CONF_ID], *args)
+    cg.add(var.set_name(config[CONF_ID].id))
+    await cg.register_component(var, config)
+    await build_stack(config, var)
+    return var

esphome/components/packet_interface/hdlc_reliability.cpp

@@ -0,0 +1,365 @@
+#include "hdlc_reliability.h"
+#ifdef USE_PACKET_INTERFACE_HDLC
+#include "esphome/core/helpers.h"
+#include "esphome/core/log.h"
+
+namespace esphome::packet_interface {
+
+ESPHOME_LOG_TAG(TAG, "packet_interface.hdlc");
+
+static constexpr uint32_t RETRANSMIT_TIMER_ID = 0;
+static constexpr uint32_t ACK_TIMER_ID = 1;
+static constexpr uint32_t SEND_RETRY_TIMER_ID = 2;
+// A frame or acknowledgement the lower layer refused, for example while a radio was receiving, is sent again after this
+static constexpr uint32_t SEND_RETRY_MS = 50;
+// SABM is repeated at this interval, or the timeout if longer, until the peer answers
+static constexpr uint32_t RESET_INTERVAL_MS = 1000;
+
+// Control byte formats, with the poll/final bit (0x10) ignored
+static constexpr uint8_t POLL_FINAL_BIT = 0x10;
+static constexpr uint8_t SUPERVISORY_FRAME = 0x01;
+static constexpr uint8_t SUPERVISORY_RR = 0x00;
+static constexpr uint8_t SUPERVISORY_REJ = 0x02;
+static constexpr uint8_t UNNUMBERED_SABM = 0x2F;
+static constexpr uint8_t UNNUMBERED_UA = 0x63;
+
+static uint16_t frame_crc(uint8_t control, const uint8_t *payload, size_t length) {
+  uint16_t crc = crc16(&control, 1);
+  return crc16(payload, length, crc);
+}
+
+HdlcReliability::HdlcReliability(PacketInterface *lower)
+    : PacketInterface(remaining_packet_size(lower->get_max_packet_size(), FRAME_OVERHEAD)), lower_(lower) {
+  this->stack_on_(lower, CAPABILITY_RELIABILITY);
+}
+
+void HdlcReliability::setup() {
+  if (this->max_packet_size_ == 0) {
+    this->mark_failed(LOG_STR("max_packet_size too small for the configured layers"));
+    return;
+  }
+  RAMAllocator<uint8_t> allocator;
+  this->tx_slots_ = allocator.allocate(size_t{this->max_queue_length_} * this->max_packet_size_);
+  if (this->tx_slots_ == nullptr) {
+    this->mark_failed(LOG_STR("Not enough memory for the send queue"));
+    return;
+  }
+  this->lower_->add_packet_interface_listener(
+      [this](const PacketBuffer &data, const PacketMetaData &meta_data) { this->receive_(data, meta_data); });
+}
+
+void HdlcReliability::dump_config() {
+  ESP_LOGCONFIG(TAG,
+                "HDLC Reliability on '%s':\n"
+                "  Max Packet Size: %zu\n"
+                "  Timeout: %" PRIu32 "ms\n"
+                "  Ack Delay: %" PRIu32 "ms\n"
+                "  Max Queue Length: %u\n"
+                "  Max Retries: %u",
+                this->name_, this->max_packet_size_, this->timeout_ms_, this->ack_delay_ms_, this->max_queue_length_,
+                this->max_retries_);
+}
+
+void HdlcReliability::loop() {
+  // Disabled first, as sending may deliver a reply to this layer and request the loop again
+  this->disable_loop();
+  if (this->state_ == LinkState::LINK_STATE_RESET_PENDING) {
+    this->state_ = LinkState::LINK_STATE_RESETTING;
+    this->start_timer_();
+    this->send_frame_(UNNUMBERED_SABM, nullptr, 0);
+  }
+  if (this->state_ != LinkState::LINK_STATE_CONNECTED)
+    return;
+  // Queued frames go first, as each carries the acknowledgement
+  if (this->send_pending_() && this->ack_due_ && !this->send_supervisory_(SUPERVISORY_RR))
+    this->retry_send_();
+}
+
+void HdlcReliability::retry_send_() {
+  this->set_timeout(SEND_RETRY_TIMER_ID, SEND_RETRY_MS, [this]() { this->request_loop_(); });
+}
+
+void HdlcReliability::owe_ack_(bool now) {
+  if (now || this->ack_delay_ms_ == 0) {
+    this->ack_due_ = true;
+    this->request_loop_();
+  } else if (!this->ack_pending_) {
+    // Waiting lets one acknowledgement cover several frames, or a reply carry it
+    this->set_timeout(ACK_TIMER_ID, this->ack_delay_ms_, [this]() {
+      this->ack_due_ = true;
+      this->request_loop_();
+    });
+  }
+  this->ack_pending_ = true;
+}
+
+void HdlcReliability::ack_sent_() {
+  this->ack_pending_ = false;
+  this->ack_due_ = false;
+  this->cancel_timeout(ACK_TIMER_ID);
+}
+
+void HdlcReliability::request_loop_() { this->enable_loop(); }
+
+bool HdlcReliability::send_to_interface(const PacketBuffer &data, const PacketMetaData &meta_data) {
+  if (this->tx_slots_ == nullptr)
+    return false;
+  size_t size = data.size();
+  if (size > this->max_packet_size_) {
+    ESP_LOGW(TAG, "%s: Packet of %zu bytes is larger than %zu", this->name_, size, this->max_packet_size_);
+    return false;
+  }
+  uint8_t outstanding = this->outstanding_();
+  if (outstanding >= this->max_queue_length_) {
+    if (this->state_ == LinkState::LINK_STATE_CONNECTED) {
+      ESP_LOGV(TAG, "%s: Send queue full", this->name_);
+    } else if (!this->reset_wait_logged_) {
+      // Once for each reset; the layers above keep trying while the peer is away
+      this->reset_wait_logged_ = true;
+      ESP_LOGD(TAG, "%s: Send queue full, waiting for the peer to answer the link reset", this->name_);
+    }
+    return false;
+  }
+  uint8_t seq = this->vs_;
+  data.copy_to(this->slot_(seq), size);
+  this->tx_lengths_[this->slot_index_(seq)] = size;
+  this->vs_ = (seq + 1) & 7;
+  // While the link is being reset, the frame waits in the queue and is sent when UA arrives
+  if (this->state_ == LinkState::LINK_STATE_CONNECTED) {
+    this->send_pending_();
+    if (outstanding == 0)
+      this->start_timer_();
+  }
+  return true;
+}
+
+bool HdlcReliability::send_frame_(uint8_t control, const uint8_t *payload, size_t length) {
+  uint16_t crc = frame_crc(control, payload, length);
+  uint8_t trailer[2] = {static_cast<uint8_t>(crc), static_cast<uint8_t>(crc >> 8)};
+  PacketBuffer body(payload, length);
+  PacketBuffer frame(&control, 1, length != 0 ? &body : nullptr, trailer, sizeof(trailer));
+  if (this->lower_->send_to_interface(frame, {}))
+    return true;
+  ESP_LOGV(TAG, "%s: Lower layer did not accept frame 0x%02X", this->name_, control);
+  return false;
+}
+
+bool HdlcReliability::send_supervisory_(uint8_t type) {
+  if (!this->send_frame_(SUPERVISORY_FRAME | (type << 2) | (this->vr_ << 5), nullptr, 0))
+    return false;
+  this->ack_sent_();
+  return true;
+}
+
+// Sends the next queued frame not yet sent, and returns true if none are left. One frame per loop pass lets other
+// components run between frames: on a radio, sending blocks, and the peer's frames are received in between. If the
+// lower layer refuses the frame, it is sent again shortly.
+bool HdlcReliability::send_pending_() {
+  if (this->vn_ == this->vs_)
+    return true;
+  uint8_t control = (this->vn_ << 1) | (this->vr_ << 5);
+  if (!this->send_frame_(control, this->slot_(this->vn_), this->tx_lengths_[this->slot_index_(this->vn_)])) {
+    this->retry_send_();
+    return false;
+  }
+  // Every I-frame carries an acknowledgement, so a pending RR is no longer needed
+  this->ack_sent_();
+  this->vn_ = (this->vn_ + 1) & 7;
+  if (this->vn_ == this->vs_)
+    return true;
+  this->request_loop_();
+  return false;
+}
+
+void HdlcReliability::resend_outstanding_() {
+  this->vn_ = this->va_;
+  this->send_pending_();
+}
+
+void HdlcReliability::start_timer_() {
+  uint32_t interval = this->timeout_ms_;
+  if (this->state_ != LinkState::LINK_STATE_CONNECTED && interval < RESET_INTERVAL_MS)
+    interval = RESET_INTERVAL_MS;
+  // Up to a quarter longer at random, so devices whose frames collided on a shared channel do not resend together
+  interval += random_uint32() % (interval / 4 + 1);
+  this->set_timeout(RETRANSMIT_TIMER_ID, interval, [this]() { this->on_timeout_(); });
+}
+
+void HdlcReliability::on_timeout_() {
+  if (this->state_ != LinkState::LINK_STATE_CONNECTED) {
+    // Counted up to max_retries_ only, so the warning is logged once until the link comes up
+    if (this->retries_ < this->max_retries_) {
+      this->retries_++;
+      if (this->retries_ == this->max_retries_) {
+        ESP_LOGW(TAG, "%s: No answer to the link reset after %u tries; check that the peer has a reliability layer",
+                 this->name_, this->max_retries_);
+      }
+    }
+    this->send_frame_(UNNUMBERED_SABM, nullptr, 0);
+    this->start_timer_();
+    return;
+  }
+  if (this->outstanding_() == 0)
+    return;
+  if (this->retries_ == this->max_retries_) {
+    ESP_LOGW(TAG, "%s: No acknowledgement after %u retries, resetting link", this->name_, this->max_retries_);
+    this->start_reset_();
+    return;
+  }
+  this->retries_++;
+  ESP_LOGV(TAG, "%s: Timeout, resending %u frames", this->name_, this->outstanding_());
+  this->resend_outstanding_();
+  this->start_timer_();
+}
+
+// Unacknowledged frames are discarded; frames queued from now on are numbered from 0 and sent once the link is up.
+// Resetting a connected link can lose data both ways, which is reported to the layers above.
+void HdlcReliability::start_reset_() {
+  bool was_connected = this->state_ == LinkState::LINK_STATE_CONNECTED;
+  this->state_ = LinkState::LINK_STATE_RESET_PENDING;
+  this->va_ = this->vs_ = this->vn_ = 0;
+  this->head_ = 0;
+  this->vr_ = 0;
+  this->retries_ = 0;
+  this->rej_sent_ = false;
+  this->ack_sent_();
+  this->cancel_timeout(RETRANSMIT_TIMER_ID);
+  this->request_loop_();
+  if (was_connected)
+    this->session_callback_.call(false);
+}
+
+void HdlcReliability::link_up_() {
+  ESP_LOGD(TAG, "%s: Link connected", this->name_);
+  this->state_ = LinkState::LINK_STATE_CONNECTED;
+  this->reset_wait_logged_ = false;
+  this->peer_frame_seen_ = false;
+  this->retries_ = 0;
+  this->cancel_timeout(RETRANSMIT_TIMER_ID);
+  if (this->outstanding_() != 0) {
+    this->resend_outstanding_();
+    this->start_timer_();
+  }
+}
+
+void HdlcReliability::process_ack_(uint8_t nr) {
+  uint8_t acked = (nr - this->va_) & 7;
+  if (acked > this->outstanding_()) {
+    ESP_LOGV(TAG, "%s: Ignoring invalid N(R) %u", this->name_, nr);
+    return;
+  }
+  if (acked == 0)
+    return;
+  // The peer may have had frames that were refused when last resent
+  if (acked > ((this->vn_ - this->va_) & 7))
+    this->vn_ = nr;
+  this->head_ = (this->head_ + acked) % this->max_queue_length_;
+  this->va_ = nr;
+  this->retries_ = 0;
+  if (this->outstanding_() == 0) {
+    this->cancel_timeout(RETRANSMIT_TIMER_ID);
+  } else {
+    this->start_timer_();
+  }
+}
+
+void HdlcReliability::receive_(const PacketBuffer &data, const PacketMetaData &meta_data) {
+  // Lower layers deliver packets in one piece; the payload is passed up without copying
+  if (!data.is_contiguous()) {
+    ESP_LOGW(TAG, "%s: Packet split across buffers is not supported", this->name_);
+    return;
+  }
+  auto frame = data.as_span();
+  if (frame.size() < FRAME_OVERHEAD) {
+    this->note_received_(false);
+    return;
+  }
+  size_t length = frame.size() - FRAME_OVERHEAD;
+  uint8_t control = frame[0];
+  const uint8_t *payload = frame.data() + 1;
+  uint16_t crc = frame[length + 1] | (frame[length + 2] << 8);
+  if (frame_crc(control, payload, length) != crc) {
+    ESP_LOGV(TAG, "%s: CRC error, frame dropped", this->name_);
+    this->note_received_(false);
+    return;
+  }
+  // The peer's packets may only be larger if it has a larger max_packet_size, which the layers above cannot take
+  if (length > this->max_packet_size_) {
+    if (!this->oversize_warned_) {
+      this->oversize_warned_ = true;
+      ESP_LOGW(TAG,
+               "%s: Frame of %zu bytes is larger than %zu, dropped; check that both devices use the same "
+               "max_packet_size",
+               this->name_, length, this->max_packet_size_);
+    } else {
+      ESP_LOGV(TAG, "%s: Frame of %zu bytes is larger than %zu, dropped", this->name_, length, this->max_packet_size_);
+    }
+    this->note_received_(false);
+    return;
+  }
+  this->note_received_(true);
+
+  uint8_t command = control & ~POLL_FINAL_BIT;
+  if (command == UNNUMBERED_SABM) {
+    // A peer that has not heard our UA repeats its SABM, and cannot have sent a numbered frame meanwhile; answering
+    // again keeps this side connected, and the queued frames, instead of treating the repeat as a restart.
+    if (this->state_ == LinkState::LINK_STATE_CONNECTED && this->peer_frame_seen_) {
+      // The peer has restarted, so frames it has not acknowledged are lost
+      ESP_LOGD(TAG, "%s: Link reset by peer", this->name_);
+      this->start_reset_();
+    }
+    this->vr_ = 0;
+    this->rej_sent_ = false;
+    this->send_frame_(UNNUMBERED_UA, nullptr, 0);
+    // Both sides now start from 0, so the link is up even if our own SABM is unanswered
+    this->link_up_();
+    return;
+  }
+  if (command == UNNUMBERED_UA) {
+    if (this->state_ == LinkState::LINK_STATE_RESETTING)
+      this->link_up_();
+    return;
+  }
+  // Numbered frames are ignored until the link is reset; the peer answers our SABM first
+  if (this->state_ != LinkState::LINK_STATE_CONNECTED)
+    return;
+  this->peer_frame_seen_ = true;
+
+  uint8_t nr = control >> 5;
+  if ((control & 1) == 0) {
+    this->process_ack_(nr);
+    this->receive_info_(control, payload, length, meta_data);
+    return;
+  }
+  if ((control & 3) != SUPERVISORY_FRAME)
+    return;
+  this->process_ack_(nr);
+  if (((control >> 2) & 3) == SUPERVISORY_REJ && this->outstanding_() != 0) {
+    ESP_LOGV(TAG, "%s: Peer rejected from %u", this->name_, nr);
+    this->resend_outstanding_();
+    this->start_timer_();
+  }
+}
+
+void HdlcReliability::receive_info_(uint8_t control, const uint8_t *payload, size_t length,
+                                    const PacketMetaData &meta_data) {
+  uint8_t ns = (control >> 1) & 7;
+  if (ns != this->vr_) {
+    // A gap or a duplicate; ask once for a resend from the expected frame, then just acknowledge at once
+    if (!this->rej_sent_) {
+      this->rej_sent_ = this->send_supervisory_(SUPERVISORY_REJ);
+      if (this->rej_sent_)
+        return;
+    }
+    this->owe_ack_(true);
+    return;
+  }
+  this->vr_ = (this->vr_ + 1) & 7;
+  this->rej_sent_ = false;
+  // The acknowledgement is sent from loop(), so a reply sent from the callback can carry it instead
+  this->owe_ack_(false);
+  this->on_receive_from_interface_(PacketBuffer(payload, length), meta_data);
+}
+
+}  // namespace esphome::packet_interface
+#endif

esphome/components/packet_interface/hdlc_reliability.h

@@ -0,0 +1,99 @@
+#pragma once
+
+#include "esphome/core/defines.h"
+#ifdef USE_PACKET_INTERFACE_HDLC
+#include <array>
+
+#include "packet_interface.h"
+
+namespace esphome::packet_interface {
+
+/**
+ * A reliability layer that delivers packets in order, without loss or duplicates, between two peers.
+ *
+ * It follows HDLC asynchronous balanced mode, with sequence numbers modulo 8 and go-back-N retransmission:
+ * - I-frames carry a payload, the sequence number N(S) and an acknowledgement N(R) of the peer's frames.
+ * - RR frames acknowledge without a payload; REJ frames ask the peer to resend from N(R).
+ * - SABM resets both peers' sequence numbers, and UA answers it.
+ *
+ * Each frame is the HDLC control byte, the payload, then a CRC-16 of both in little endian order.
+ * Unacknowledged frames are resent after the timeout; after max_retries the link is reset.
+ */
+class HdlcReliability : public PacketInterface {
+ public:
+  /// Most frames that can be unacknowledged at once, set by the 3 bit sequence numbers.
+  static constexpr uint8_t MAX_WINDOW = 7;
+  /// Control byte plus CRC-16.
+  static constexpr size_t FRAME_OVERHEAD = 3;
+
+  explicit HdlcReliability(PacketInterface *lower);
+
+  void setup() override;
+  void loop() override;
+  void dump_config() override;
+  bool send_to_interface(const PacketBuffer &data, const PacketMetaData &meta_data) override;
+  /// No room while the layer has no send queue: before setup(), or when setup() failed.
+  size_t get_send_capacity() const override {
+    return this->tx_slots_ == nullptr ? 0 : this->max_queue_length_ - this->outstanding_();
+  }
+
+  void set_ack_timeout(uint32_t timeout_ms) { this->timeout_ms_ = timeout_ms; }
+  void set_ack_delay(uint32_t ack_delay_ms) { this->ack_delay_ms_ = ack_delay_ms; }
+  void set_max_queue_length(uint8_t length) { this->max_queue_length_ = length; }
+  void set_max_retries(uint8_t retries) { this->max_retries_ = retries; }
+
+  bool is_connected() const { return this->state_ == LinkState::LINK_STATE_CONNECTED; }
+
+ protected:
+  enum class LinkState : uint8_t {
+    LINK_STATE_RESET_PENDING,  // SABM to be sent from loop()
+    LINK_STATE_RESETTING,      // SABM sent, waiting for UA
+    LINK_STATE_CONNECTED,
+  };
+
+  void receive_(const PacketBuffer &data, const PacketMetaData &meta_data);
+  void receive_info_(uint8_t control, const uint8_t *payload, size_t length, const PacketMetaData &meta_data);
+  bool send_frame_(uint8_t control, const uint8_t *payload, size_t length);
+  bool send_supervisory_(uint8_t type);
+  bool send_pending_();
+  void resend_outstanding_();
+  void retry_send_();
+  /// An RR is owed: at once, or after the ack delay unless an I-frame carries it first.
+  void owe_ack_(bool now);
+  void ack_sent_();
+  void process_ack_(uint8_t nr);
+  void on_timeout_();
+  void start_reset_();
+  void link_up_();
+  void start_timer_();
+  void request_loop_();
+  uint8_t outstanding_() const { return (this->vs_ - this->va_) & 7; }
+  uint8_t slot_index_(uint8_t seq) const { return (this->head_ + ((seq - this->va_) & 7)) % this->max_queue_length_; }
+  uint8_t *slot_(uint8_t seq) { return this->tx_slots_ + this->slot_index_(seq) * this->max_packet_size_; }
+
+  PacketInterface *lower_;
+  // max_queue_length_ slots of max_packet_size_ bytes, a ring starting at head_ which holds frame va_; allocated in
+  // setup() and never freed
+  uint8_t *tx_slots_{nullptr};
+  std::array<uint16_t, MAX_WINDOW> tx_lengths_{};  // indexed like the slots
+  uint32_t timeout_ms_{200};
+  uint32_t ack_delay_ms_{0};
+  uint8_t max_queue_length_{4};
+  uint8_t max_retries_{5};
+  uint8_t retries_{0};
+  uint8_t head_{0};
+  uint8_t vs_{0};  // sequence number of the next new frame
+  uint8_t vn_{0};  // next frame to send; frames from va_ up to it have been sent
+  uint8_t va_{0};  // oldest unacknowledged frame
+  uint8_t vr_{0};  // next frame expected from the peer
+  LinkState state_{LinkState::LINK_STATE_RESET_PENDING};
+  bool ack_pending_{false};  // an RR is owed
+  bool ack_due_{false};      // and should be sent now
+  bool rej_sent_{false};
+  bool peer_frame_seen_{false};  // a numbered frame has arrived since the link came up
+  bool oversize_warned_{false};
+  bool reset_wait_logged_{false};  // the queue filled while waiting for this reset to be answered
+};
+
+}  // namespace esphome::packet_interface
+#endif

esphome/components/packet_interface/layers/__init__.py

@@ -0,0 +1,104 @@
+"""The kinds of layer that can be stacked on a packet interface, and the registry of their implementations.
+
+Each module in this package implements one layer type and registers it with its kind, for example:
+
+    @RELIABILITY.register("hdlc", schema=HDLC_SCHEMA)
+    async def build_hdlc(config: ConfigType, lower: MockObj) -> MockObj:
+        ...
+
+The packet_interface component imports every module here before it builds its schemas, so a new layer type needs
+only a new module. The kinds, and the order in which they are stacked, are fixed here.
+"""
+
+from collections.abc import Awaitable, Callable
+from dataclasses import dataclass
+from typing import Any
+
+import esphome.codegen as cg
+import esphome.config_validation as cv
+from esphome.const import CONF_TYPE
+from esphome.cpp_generator import MockObj
+from esphome.types import ConfigType
+
+packet_interface_ns = cg.esphome_ns.namespace("packet_interface")
+PacketInterface = packet_interface_ns.class_("PacketInterface", cg.Component)
+
+CONF_RELIABILITY = "reliability"
+
+# Builds a layer above lower and returns it
+LayerBuilder = Callable[[ConfigType, MockObj], Awaitable[Any]]
+
+
+@dataclass(frozen=True)
+class LayerType:
+    """One implementation of a kind of layer."""
+
+    schema: Any
+    build: LayerBuilder
+
+
+class LayerKind:
+    """A kind of layer, such as reliability, with the types that implement it."""
+
+    def __init__(self, key: str, default_type: str) -> None:
+        self.key = key
+        self.default_type = default_type
+        self.types: dict[str, LayerType] = {}
+        # Set once the schema is built, as types registered after that would not be in it
+        self.frozen = False
+
+    def register(
+        self, name: str, *, schema: Any
+    ) -> Callable[[LayerBuilder], LayerBuilder]:
+        """Register a type with its schema."""
+
+        def decorator(build: LayerBuilder) -> LayerBuilder:
+            if self.frozen:
+                raise ValueError(
+                    f"{self.key} layer type '{name}' is registered after the schemas were built; register it "
+                    "before the packet_interface component is imported"
+                )
+            if name in self.types:
+                raise ValueError(
+                    f"{self.key} layer type '{name}' is already registered"
+                )
+            self.types[name] = LayerType(schema, build)
+            return build
+
+        return decorator
+
+    @staticmethod
+    def _expand(value: Any) -> Any:
+        """Allow a layer to be enabled with no options, as in `reliability:`."""
+        return {} if value is None else value
+
+    def schema(self) -> Callable[[Any], ConfigType]:
+        """The schema for this kind; no type can be registered after this."""
+        self.frozen = True
+        return cv.All(
+            self._expand,
+            cv.typed_schema(
+                {name: layer.schema for name, layer in self.types.items()},
+                default_type=self.default_type,
+            ),
+        )
+
+    def get_type(self, config: ConfigType) -> LayerType:
+        return self.types[config[CONF_TYPE]]
+
+
+RELIABILITY = LayerKind(CONF_RELIABILITY, "hdlc")
+# The kinds stacked above the link, from the bottom up
+STACK_ORDER = (RELIABILITY,)
+
+
+def stack_schema() -> dict:
+    """Schema entries for the layers of one stack; call only once all layer types are registered."""
+    return {cv.Optional(kind.key): kind.schema() for kind in STACK_ORDER}
+
+
+async def build_stack(config: ConfigType, lower: MockObj) -> None:
+    """Create the layers configured in config, from the bottom up, above lower."""
+    for kind in STACK_ORDER:
+        if (layer := config.get(kind.key)) is not None:
+            lower = await kind.get_type(layer).build(layer, lower)

esphome/components/packet_interface/layers/hdlc_reliability.py

@@ -0,0 +1,59 @@
+"""Reliability layer using HDLC style acknowledgement and go-back-N retransmission."""
+
+import esphome.codegen as cg
+import esphome.config_validation as cv
+from esphome.const import CONF_ID, CONF_TIMEOUT
+from esphome.cpp_generator import MockObj
+from esphome.types import ConfigType
+
+from . import RELIABILITY, PacketInterface, packet_interface_ns
+
+CONF_ACK_DELAY = "ack_delay"
+CONF_MAX_QUEUE_LENGTH = "max_queue_length"
+CONF_MAX_RETRIES = "max_retries"
+
+HdlcReliability = packet_interface_ns.class_("HdlcReliability", PacketInterface)
+
+
+def _ack_delay_within_timeout(config: ConfigType) -> ConfigType:
+    """The peer, configured the same, must hear the acknowledgement before its timeout."""
+    if (
+        config[CONF_ACK_DELAY].total_milliseconds
+        >= config[CONF_TIMEOUT].total_milliseconds
+    ):
+        raise cv.Invalid(
+            f"Must be shorter than '{CONF_TIMEOUT}'", path=[CONF_ACK_DELAY]
+        )
+    return config
+
+
+HDLC_SCHEMA = cv.All(
+    cv.Schema(
+        {
+            cv.GenerateID(): cv.declare_id(HdlcReliability),
+            # Retransmitting more often than the main loop runs would exhaust the retries at once
+            cv.Optional(CONF_TIMEOUT, default="200ms"): cv.All(
+                cv.positive_time_period_milliseconds,
+                cv.Range(min=cv.TimePeriod(milliseconds=50)),
+            ),
+            cv.Optional(
+                CONF_ACK_DELAY, default="0ms"
+            ): cv.positive_time_period_milliseconds,
+            cv.Optional(CONF_MAX_QUEUE_LENGTH, default=4): cv.int_range(1, 7),
+            cv.Optional(CONF_MAX_RETRIES, default=5): cv.int_range(1, 255),
+        }
+    ).extend(cv.COMPONENT_SCHEMA),
+    _ack_delay_within_timeout,
+)
+
+
+@RELIABILITY.register("hdlc", schema=HDLC_SCHEMA)
+async def build_hdlc(config: ConfigType, lower: MockObj) -> MockObj:
+    cg.add_define("USE_PACKET_INTERFACE_HDLC")
+    var = cg.new_Pvariable(config[CONF_ID], lower)
+    cg.add(var.set_ack_timeout(config[CONF_TIMEOUT]))
+    cg.add(var.set_ack_delay(config[CONF_ACK_DELAY]))
+    cg.add(var.set_max_queue_length(config[CONF_MAX_QUEUE_LENGTH]))
+    cg.add(var.set_max_retries(config[CONF_MAX_RETRIES]))
+    await cg.register_component(var, config)
+    return var

esphome/components/packet_interface/packet_buffer.h

@@ -0,0 +1,173 @@
+#pragma once
+
+#include <cstddef>
+#include <cstdint>
+#include <cstring>
+#include <span>
+#include <vector>
+
+namespace esphome::packet_interface {
+
+/**
+ * A buffer class that efficiently represents a composite buffer with three sections:
+ * - pre_buffer: A pointer to uint8_t data with a length
+ * - mid_buffer: A reference to another PacketBuffer (optional)
+ * - post_buffer: A pointer to uint8_t data with a length
+ *
+ * This allows efficient zero-copy composition of buffers without allocating new memory.
+ *
+ * WARNING: PacketBuffer holds raw pointers to data. The user must ensure that the data remains valid
+ * for the lifetime of the PacketBuffer instance. Storing PacketBuffer instances beyond the scope of the data they
+ * reference will lead to dangling pointers and undefined behavior, so to keep a packet, copy it with copy_to() into a
+ * buffer allocated in setup().
+ */
+class PacketBuffer {
+ public:
+  PacketBuffer() = default;
+
+  // Disable copy semantics - PacketBuffer contains pointers and copying would create dangling references
+  PacketBuffer(const PacketBuffer &) = delete;
+  PacketBuffer &operator=(const PacketBuffer &) = delete;
+
+  // Enable move semantics
+  PacketBuffer(PacketBuffer &&) = default;
+  PacketBuffer &operator=(PacketBuffer &&) = default;
+
+  /**
+   * Construct from a single buffer.
+   */
+  PacketBuffer(const uint8_t *data, size_t length) : pre_buffer_(data), pre_length_(length) {}
+
+  /**
+   * Construct from a vector.
+   */
+  explicit PacketBuffer(const std::vector<uint8_t> &vec) : pre_buffer_(vec.data()), pre_length_(vec.size()) {}
+  // A temporary vector would leave the buffer dangling
+  explicit PacketBuffer(std::vector<uint8_t> &&) = delete;
+
+  /**
+   * Construct with pre and post buffers.
+   */
+  PacketBuffer(const uint8_t *pre_data, size_t pre_length, const uint8_t *post_data, size_t post_length)
+      : pre_buffer_(pre_data), pre_length_(pre_length), post_buffer_(post_data), post_length_(post_length) {}
+
+  /**
+   * Construct with pre, mid, and post buffers.
+   */
+  PacketBuffer(const uint8_t *pre_data, size_t pre_length, const PacketBuffer *mid_buffer, const uint8_t *post_data,
+               size_t post_length)
+      : pre_buffer_(pre_data),
+        pre_length_(pre_length),
+        mid_buffer_(mid_buffer),
+        post_buffer_(post_data),
+        post_length_(post_length) {}
+
+  /**
+   * Get the total size of the buffer.
+   */
+  size_t size() const {
+    size_t total = this->pre_length_ + this->post_length_;
+    if (this->mid_buffer_ != nullptr) {
+      total += this->mid_buffer_->size();
+    }
+    return total;
+  }
+
+  /**
+   * Check if the buffer is empty.
+   */
+  bool empty() const { return this->size() == 0; }
+
+  /**
+   * Check if all the data is held in the pre-buffer, so it can be read as one span.
+   */
+  bool is_contiguous() const { return this->mid_buffer_ == nullptr && this->post_length_ == 0; }
+
+  /**
+   * Get the data as one span. Only valid when is_contiguous() is true.
+   */
+  std::span<const uint8_t> as_span() const { return {this->pre_buffer_, this->pre_length_}; }
+
+  /**
+   * Access a byte at a specific position.
+   * @param index The position to access
+   * @return The byte at the specified position, or 0 past the end
+   */
+  uint8_t operator[](size_t index) const {
+    if (index < this->pre_length_) {
+      return this->pre_buffer_[index];
+    }
+    index -= this->pre_length_;
+
+    if (this->mid_buffer_ != nullptr) {
+      size_t mid_size = this->mid_buffer_->size();
+      if (index < mid_size) {
+        return (*this->mid_buffer_)[index];
+      }
+      index -= mid_size;
+    }
+
+    return index < this->post_length_ ? this->post_buffer_[index] : 0;
+  }
+
+  /**
+   * Copy data from the buffer to a destination pointer.
+   * @param dest Destination pointer
+   * @param count Number of bytes to copy
+   * @param offset Offset in the source buffer to start copying from
+   * @return Number of bytes actually copied
+   */
+  size_t copy_to(uint8_t *dest, size_t count, size_t offset = 0) const {
+    size_t total_size = this->size();
+    if (offset >= total_size) {
+      return 0;
+    }
+
+    size_t available = total_size - offset;
+    size_t to_copy = count < available ? count : available;
+    size_t copied = 0;
+
+    // Copy from pre_buffer
+    if (offset < this->pre_length_) {
+      size_t pre_offset = offset;
+      size_t pre_available = this->pre_length_ - pre_offset;
+      size_t pre_copy = to_copy < pre_available ? to_copy : pre_available;
+      std::memcpy(dest, this->pre_buffer_ + pre_offset, pre_copy);
+      copied += pre_copy;
+      dest += pre_copy;
+      offset += pre_copy;
+    }
+
+    // Copy from mid_buffer
+    size_t mid_size = this->mid_buffer_ != nullptr ? this->mid_buffer_->size() : 0;
+    if (copied < to_copy && offset < this->pre_length_ + mid_size) {
+      size_t mid_offset = offset - this->pre_length_;
+      size_t mid_available = mid_size - mid_offset;
+      size_t mid_copy = (to_copy - copied) < mid_available ? (to_copy - copied) : mid_available;
+      this->mid_buffer_->copy_to(dest, mid_copy, mid_offset);
+      copied += mid_copy;
+      dest += mid_copy;
+      offset += mid_copy;
+    }
+
+    // Copy from post_buffer
+    if ((copied < to_copy) && (this->post_length_ > 0)) {
+      size_t post_offset = offset - this->pre_length_ - mid_size;
+      size_t post_available = this->post_length_ - post_offset;
+      size_t post_copy = (to_copy - copied) < post_available ? (to_copy - copied) : post_available;
+      std::memcpy(dest, this->post_buffer_ + post_offset, post_copy);
+      copied += post_copy;
+    }
+
+    return copied;
+  }
+
+ private:
+  const uint8_t *pre_buffer_{nullptr};
+  size_t pre_length_{0};
+  const PacketBuffer *mid_buffer_{nullptr};
+  const uint8_t *post_buffer_{nullptr};
+  size_t post_length_{0};
+};
+
+}  // namespace esphome::packet_interface

esphome/components/packet_interface/packet_interface.cpp

@@ -0,0 +1,39 @@
+#include "packet_interface.h"
+#include "esphome/core/log.h"
+
+namespace esphome::packet_interface {
+
+ESPHOME_LOG_TAG(TAG, "packet_interface");
+
+// Packets in a row that cannot be understood before the mismatch is logged
+static constexpr uint8_t MISMATCH_COUNT = 10;
+
+void PacketInterface::dump_config() {
+  ESP_LOGCONFIG(TAG,
+                "Packet Interface '%s':\n"
+                "  Max Packet Size: %zu",
+                this->name_, this->get_max_packet_size());
+}
+
+void PacketInterface::on_receive_from_interface_(const PacketBuffer &data, const PacketMetaData &meta_data) {
+#ifdef ESPHOME_LOG_HAS_VERBOSE
+  static constexpr size_t LOG_BYTES = 24;
+  uint8_t head[LOG_BYTES];
+  size_t len = data.copy_to(head, LOG_BYTES);
+  ESP_LOGV_HEX(TAG, head, len, LOG_BYTES, "%s: received %zu bytes %s", this->name_, data.size());
+#endif
+  this->callback_.call(data, meta_data);
+}
+
+void PacketInterface::note_received_(bool understood) {
+  if (understood) {
+    this->not_understood_count_ = 0;
+  } else if (this->not_understood_count_ < MISMATCH_COUNT) {
+    this->not_understood_count_++;
+    if (this->not_understood_count_ == MISMATCH_COUNT) {
+      ESP_LOGW(TAG, "%s: %u packets in a row could not be understood; check that both ends have the same layers",
+               this->name_, MISMATCH_COUNT);
+    }
+  }
+}
+}  // namespace esphome::packet_interface

esphome/components/packet_interface/packet_interface.h

@@ -0,0 +1,149 @@
+#pragma once
+
+#include <cmath>
+#include <cstddef>
+#include <cstdint>
+#include <utility>
+
+#include "esphome/core/string_ref.h"
+#include "esphome/core/helpers.h"
+#include "esphome/core/component.h"
+#include "packet_buffer.h"
+
+namespace esphome::packet_interface {
+
+/// The room left for a packet of \p size bytes after \p used bytes, or 0 if it is too small.
+constexpr size_t remaining_packet_size(size_t size, size_t used) { return size > used ? size - used : 0; }
+
+/// What a stack of layers provides, as bits of PacketInterface::get_capabilities().
+enum Capability : uint8_t {
+  CAPABILITY_ENCRYPTION = 1 << 0,
+  CAPABILITY_RELIABILITY = 1 << 1,
+  CAPABILITY_SESSION = 1 << 2,
+  CAPABILITY_ADDRESSING = 1 << 3,
+  CAPABILITY_FRAGMENTATION = 1 << 4,
+};
+
+/**
+ * A struct to hold metadata about a packet.
+ * @param info Additional information about the packet
+ * @param source_address With an addressing layer, the sender of a received packet; 0 if not known
+ * @param destination_address With an addressing layer, the destination of a packet; when sending, 0 uses the
+ * configured destination
+ * @param rssi The RSSI of the packet
+ * @param snr The SNR of the packet
+ * @param mac_address The MAC address of the sender/receiver
+ */
+class PacketMetaData {
+ public:
+  StringRef info{};
+  uint16_t source_address{0};
+  uint16_t destination_address{0};
+  float rssi{NAN};
+  float snr{NAN};
+  uint8_t mac_address[MAC_ADDRESS_SIZE]{};
+};
+/**
+ * A class that will transport data to and from an abstract channel.
+ *
+ * The operations defined are:
+ *
+ * Transmit: the function send_to_interface() takes a PacketBuffer of bytes, and returns when all data is
+ * written or buffered for transmission.
+ *
+ * Receive: The callbacks for an instance of this class are called with currently received data.
+ */
+class PacketInterface : public Component {
+ public:
+  /**
+   *
+   * Method to be implemented by child classes to send data to the interface.
+   *
+   * @param data The data to be sent
+   * @param meta_data Metadata about the packet to be sent
+   * @return True if the data was queued for transmission, false if it could not be sent
+   */
+  virtual bool send_to_interface(const PacketBuffer &data, const PacketMetaData &meta_data) = 0;
+
+  /// The largest packet this layer accepts; fixed when the layer is constructed.
+  size_t get_max_packet_size() const { return this->max_packet_size_; }
+  /// How many packets send_to_interface() would accept now, so a layer above can tell before sending a series.
+  virtual size_t get_send_capacity() const { return SIZE_MAX; }
+  /// The capabilities of this layer and every layer below it.
+  uint8_t get_capabilities() const { return this->capabilities_; }
+  bool has_capability(Capability capability) const { return (this->capabilities_ & capability) != 0; }
+  /**
+   * With CAPABILITY_SESSION, the callback is called with true when the peer can be reached, including after it
+   * restarts, and with false when it is lost. The session layer is always the top layer, so register on top().
+   * A reliability layer calls it with false when it resets the link and discards data, which the session layer above
+   * reports as the session lost.
+   */
+  template<typename F> void add_on_session_state_callback(F &&callback) {
+    this->session_callback_.add(std::forward<F>(callback));
+  }
+
+  /// The topmost layer stacked on this one, or this one if nothing is stacked on it.
+  PacketInterface *top() {
+    PacketInterface *layer = this;
+    while (layer->upper_ != nullptr)
+      layer = layer->upper_;
+    return layer;
+  }
+  /// Name shown in log messages; a layer takes the name of the link it is stacked on.
+  void set_name(const char *name) { this->name_ = name; }
+  const char *get_name() const { return this->name_; }
+
+  /**
+   * Add a listener that will be called when data is received.
+   *
+   * @param callback The callback to be called when data is received.
+   */
+  template<typename F> void add_packet_interface_listener(F &&callback) {
+    this->callback_.add(std::forward<F>(callback));
+  }
+
+  void dump_config() override;
+
+ protected:
+  /// @param max_packet_size The largest packet the layer accepts, set from the layer below or the layer's own buffer
+  explicit PacketInterface(size_t max_packet_size) : max_packet_size_(max_packet_size) {}
+
+  virtual ~PacketInterface() = default;
+  /**
+   * This function should be called by implementing classes with received data to be passed to any listeners.
+   *
+   * @param data The received data
+   * @param meta_data Metadata about the received packet
+   */
+  void on_receive_from_interface_(const PacketBuffer &data, const PacketMetaData &meta_data);
+  /**
+   * Called by a layer for each received packet it understood, or could not make sense of. A run of packets that
+   * cannot be understood usually means the peer has different layers configured, which is logged once per run.
+   */
+  void note_received_(bool understood);
+  /// Called by a layer's constructor to record itself as the layer above \p lower, adding its own capability.
+  void stack_on_(PacketInterface *lower, Capability capability) {
+    lower->upper_ = this;
+    this->inherit_from_(lower, capability);
+  }
+  /// Takes the name and capabilities of `lower` without becoming its top, for one of several stacks on a link.
+  void inherit_from_(PacketInterface *lower, Capability capability) {
+    this->name_ = lower->name_;
+    this->capabilities_ = lower->capabilities_ | capability;
+    // A link that has a session of its own, such as TCP, reports it to whatever is stacked above, as does a
+    // reliability layer that discards data; the session layer handles the latter itself
+    if ((lower->has_capability(CAPABILITY_SESSION) || lower->has_capability(CAPABILITY_RELIABILITY)) &&
+        capability != CAPABILITY_SESSION) {
+      lower->add_on_session_state_callback([this](bool connected) { this->session_callback_.call(connected); });
+    }
+  }
+
+  LazyCallbackManager<void(const PacketBuffer &, const PacketMetaData &)> callback_;
+  LazyCallbackManager<void(bool)> session_callback_;
+  PacketInterface *upper_{nullptr};
+  const char *name_{""};
+  const size_t max_packet_size_;
+  uint8_t capabilities_{0};
+  uint8_t not_understood_count_{0};
+};
+}  // namespace esphome::packet_interface

esphome/components/packet_interface/packet_transport/__init__.py

@@ -0,0 +1,28 @@
+import esphome.codegen as cg
+from esphome.components.packet_transport import (
+    PacketTransport,
+    new_packet_transport,
+    transport_schema,
+)
+import esphome.config_validation as cv
+from esphome.types import ConfigType
+
+from .. import CONF_PACKET_INTERFACE, PacketInterface, packet_interface_ns
+
+CODEOWNERS = ["@clydebarrow"]
+DEPENDENCIES = ["packet_interface"]
+
+PacketInterfaceTransport = packet_interface_ns.class_(
+    "PacketInterfaceTransport", PacketTransport
+)
+
+CONFIG_SCHEMA = transport_schema(PacketInterfaceTransport).extend(
+    {
+        cv.GenerateID(CONF_PACKET_INTERFACE): cv.use_id(PacketInterface),
+    }
+)
+
+
+async def to_code(config: ConfigType) -> None:
+    interface = await cg.get_variable(config[CONF_PACKET_INTERFACE])
+    await new_packet_transport(config, interface)

esphome/components/packet_interface/packet_transport/packet_interface_transport.cpp

@@ -0,0 +1,29 @@
+#include "packet_interface_transport.h"
+#include "esphome/core/log.h"
+
+namespace esphome::packet_interface {
+
+ESPHOME_LOG_TAG(TAG, "packet_interface.transport");
+
+void PacketInterfaceTransport::setup() {
+  PacketTransport::setup();
+  this->interface_ = this->interface_->top();
+  this->interface_->add_packet_interface_listener(
+      [this](const PacketBuffer &data, const PacketMetaData &) { this->receive_(data); });
+}
+
+void PacketInterfaceTransport::receive_(const PacketBuffer &data) {
+  // Packet interface layers deliver packets in one piece
+  if (!data.is_contiguous()) {
+    ESP_LOGW(TAG, "Packet split across buffers is not supported");
+    return;
+  }
+  this->process_(data.as_span());
+}
+
+void PacketInterfaceTransport::send_packet(const std::vector<uint8_t> &buf) const {
+  if (!this->interface_->send_to_interface(PacketBuffer(buf), {}))
+    ESP_LOGD(TAG, "Failed to send packet of %zu bytes", buf.size());
+}
+
+}  // namespace esphome::packet_interface

esphome/components/packet_interface/packet_transport/packet_interface_transport.h

@@ -0,0 +1,29 @@
+#pragma once
+
+#include "esphome/components/packet_interface/packet_interface.h"
+#include "esphome/components/packet_transport/packet_transport.h"
+
+namespace esphome::packet_interface {
+
+/**
+ * A transport protocol adapter that bridges PacketInterface to PacketTransport.
+ * This allows packet_transport functionality to be used with any PacketInterface implementation.
+ */
+class PacketInterfaceTransport : public packet_transport::PacketTransport {
+ public:
+  explicit PacketInterfaceTransport(PacketInterface *interface) : interface_(interface) {}
+
+  void setup() override;
+
+  float get_setup_priority() const override { return setup_priority::PROCESSOR; }
+
+ protected:
+  // implementing PacketTransport virtual methods
+  size_t get_max_packet_size() override { return this->interface_->top()->get_max_packet_size(); }
+  void send_packet(const std::vector<uint8_t> &buf) const override;
+  void receive_(const PacketBuffer &data);
+
+  PacketInterface *interface_;
+};
+
+}  // namespace esphome::packet_interface

esphome/components/packet_transport/__init__.py

@@ -205,8 +205,10 @@ async def register_packet_transport(var: MockObj, config: ConfigType) -> set[str
     return providers
 
 
-async def new_packet_transport(config: ConfigType) -> tuple[MockObj, set[str]]:
-    var = cg.new_Pvariable(config[CONF_ID])
+async def new_packet_transport(
+    config: ConfigType, *args: Any
+) -> tuple[MockObj, set[str]]:
+    var = cg.new_Pvariable(config[CONF_ID], *args)
     cg.add(var.set_platform_name(config[CONF_PLATFORM]))
     providers = await register_packet_transport(var, config)
     return var, providers

esphome/components/packet_transport/packet_transport.cpp

@@ -547,9 +547,11 @@ void PacketTransport::dump_config() {
   ESP_LOGCONFIG(TAG,
                 "Packet Transport:\n"
                 "  Platform: %s\n"
+                "  Max Packet Size: %zu\n"
                 "  Encrypted: %s\n"
                 "  Ping-pong: %s",
-                this->platform_name_, YESNO(this->is_encrypted_()), YESNO(this->ping_pong_enable_));
+                this->platform_name_, this->get_max_packet_size(), YESNO(this->is_encrypted_()),
+                YESNO(this->ping_pong_enable_));
 #ifdef USE_SENSOR
   for (const auto &sensor : this->sensors_) {
     ESP_LOGCONFIG(TAG, "  Sensor: %s", sensor.id);

esphome/components/uart/packet_interface/__init__.py

@@ -0,0 +1,36 @@
+import esphome.codegen as cg
+from esphome.components import packet_interface, uart
+from esphome.components.packet_interface import (
+    CONF_MAX_PACKET_SIZE,
+    packet_interface_schema,
+)
+from esphome.const import CONF_ID
+from esphome.types import ConfigType
+
+from .. import uart_ns
+
+CODEOWNERS = ["@clydebarrow"]
+
+DEPENDENCIES = ["uart"]
+
+UartPacketInterface = uart_ns.class_(
+    "UartPacketInterface",
+    packet_interface.PacketInterface,
+    uart.UARTDevice,
+)
+
+CONFIG_SCHEMA = packet_interface_schema(UartPacketInterface, 508).extend(
+    uart.UART_DEVICE_SCHEMA
+)
+
+
+async def to_code(config: ConfigType) -> None:
+    # The receive buffer's size is known here, so it is a static array rather than allocated at run time
+    rx_buffer = f"{config[CONF_ID].id}__rx_buffer"
+    cg.add_global(
+        cg.RawStatement(f"static uint8_t {rx_buffer}[{config[CONF_MAX_PACKET_SIZE]}];")
+    )
+    var = await packet_interface.new_packet_interface(
+        config, cg.RawExpression(rx_buffer)
+    )
+    await uart.register_uart_device(var, config)

esphome/components/uart/packet_interface/uart_packet_interface.cpp

@@ -0,0 +1,85 @@
+#include "esphome/core/log.h"
+#include "uart_packet_interface.h"
+
+namespace esphome::uart {
+
+using packet_interface::PacketBuffer;
+using packet_interface::PacketMetaData;
+
+ESPHOME_LOG_TAG(TAG, "uart.packet_interface");
+
+static constexpr uint8_t FLAG_BYTE = 0x7E;
+static constexpr uint8_t CONTROL_BYTE = 0x7D;
+static constexpr uint8_t ESCAPE_XOR = 0x20;
+// Raw bytes escaped and written per UART write
+static constexpr size_t TX_CHUNK_SIZE = 32;
+
+void UartPacketInterface::loop() {
+  while (this->available()) {
+    uint8_t byte;
+    if (!this->read_byte(&byte)) {
+      ESP_LOGW(TAG, "Failed to read byte from UART");
+      return;
+    }
+    if (byte == FLAG_BYTE) {
+      // A flag that ends a frame also starts the next, so an unfinished frame cannot hide the one after it
+      if (this->rx_started_ && this->rx_length_ != 0)
+        this->on_receive_from_interface_(PacketBuffer(this->rx_buffer_.data(), this->rx_length_), {});
+      this->rx_started_ = true;
+      this->rx_length_ = 0;
+      this->rx_control_ = false;
+      continue;
+    }
+    if (!this->rx_started_)
+      continue;
+    if (byte == CONTROL_BYTE) {
+      this->rx_control_ = true;
+      continue;
+    }
+    if (this->rx_control_) {
+      byte ^= ESCAPE_XOR;
+      this->rx_control_ = false;
+    }
+    if (this->rx_length_ >= this->rx_buffer_.size()) {
+      ESP_LOGD(TAG, "Packet too large, discarding");
+      this->rx_started_ = false;
+      this->rx_length_ = 0;
+      continue;
+    }
+    this->rx_buffer_[this->rx_length_++] = byte;
+  }
+}
+
+bool UartPacketInterface::send_to_interface(const PacketBuffer &data, const PacketMetaData &meta_data) {
+  size_t size = data.size();
+  if (size == 0)
+    return true;
+  if (size > this->max_packet_size_) {
+    ESP_LOGW(TAG, "Packet of %zu bytes is larger than %zu", size, this->max_packet_size_);
+    return false;
+  }
+  uint8_t raw[TX_CHUNK_SIZE]{};
+  // Every byte may be escaped, plus a flag byte at each end
+  uint8_t out[TX_CHUNK_SIZE * 2 + 2];
+  size_t out_len = 0;
+  out[out_len++] = FLAG_BYTE;
+  for (size_t offset = 0; offset < size;) {
+    size_t count = data.copy_to(raw, TX_CHUNK_SIZE, offset);
+    offset += count;
+    for (size_t i = 0; i != count; i++) {
+      uint8_t byte = raw[i];
+      if (byte == FLAG_BYTE || byte == CONTROL_BYTE) {
+        out[out_len++] = CONTROL_BYTE;
+        byte ^= ESCAPE_XOR;
+      }
+      out[out_len++] = byte;
+    }
+    if (offset == size)
+      out[out_len++] = FLAG_BYTE;
+    this->write_array(out, out_len);
+    out_len = 0;
+  }
+  return true;
+}
+
+}  // namespace esphome::uart

esphome/components/uart/packet_interface/uart_packet_interface.h

@@ -0,0 +1,35 @@
+#pragma once
+
+#include <span>
+
+#include "esphome/components/packet_interface/packet_interface.h"
+#include "esphome/components/uart/uart.h"
+
+namespace esphome::uart {
+
+/**
+ * A packet interface for sending and receiving framed packets over a UART connection.
+ * Uses simple byte-stuffing framing with FLAG_BYTE and CONTROL_BYTE.
+ * The protocol wraps data between FLAG_BYTEs.
+ * Any occurrence of FLAG_BYTE or CONTROL_BYTE in the data is escaped by emitting CONTROL_BYTE followed by the byte
+ * XORed with 0x20.
+ */
+class UartPacketInterface : public packet_interface::PacketInterface, public UARTDevice {
+ public:
+  /// @param rx_buffer Holds the unescaped data being received; its size is the largest packet, and it must outlive
+  /// the link
+  explicit UartPacketInterface(std::span<uint8_t> rx_buffer)
+      : packet_interface::PacketInterface(rx_buffer.size()), rx_buffer_(rx_buffer) {}
+
+  void loop() override;
+  bool send_to_interface(const packet_interface::PacketBuffer &data,
+                         const packet_interface::PacketMetaData &meta_data) override;
+
+ protected:
+  const std::span<uint8_t> rx_buffer_;
+  size_t rx_length_{0};
+  bool rx_started_{};
+  bool rx_control_{};
+};
+
+}  // namespace esphome::uart

esphome/components/uart/packet_transport/uart_transport.cpp

@@ -6,6 +6,10 @@ namespace esphome::uart {
 
 ESPHOME_LOG_TAG(TAG, "uart_transport");
 
+static constexpr uint16_t MAX_PACKET_SIZE = 508;
+static constexpr uint8_t FLAG_BYTE = 0x7E;
+static constexpr uint8_t CONTROL_BYTE = 0x7D;
+
 void UARTTransport::loop() {
   PacketTransport::loop();
 
@@ -78,4 +82,5 @@ void UARTTransport::send_packet(const std::vector<uint8_t> &buf) const {
   this->parent_->write_byte(FLAG_BYTE);
 }
 
+size_t UARTTransport::get_max_packet_size() { return MAX_PACKET_SIZE; }
 }  // namespace esphome::uart

esphome/components/uart/packet_transport/uart_transport.h

@@ -16,9 +16,6 @@ namespace esphome::uart {
  * Any occurrence of FLAG_BYTE or CONTROL_BYTE in the data is escaped by emitting CONTROL_BYTE followed by the byte
  * XORed with 0x20.
  */
-static const uint16_t MAX_PACKET_SIZE = 508;
-static const uint8_t FLAG_BYTE = 0x7E;
-static const uint8_t CONTROL_BYTE = 0x7D;
 
 class UARTTransport final : public packet_transport::PacketTransport, public UARTDevice {
  public:
@@ -29,7 +26,7 @@ class UARTTransport final : public packet_transport::PacketTransport, public UAR
   void write_byte_(uint8_t byte) const;
   void send_packet(const std::vector<uint8_t> &buf) const override;
   bool should_send() override { return true; };
-  size_t get_max_packet_size() override { return MAX_PACKET_SIZE; }
+  size_t get_max_packet_size() override;
   std::vector<uint8_t> receive_buffer_{};
   bool rx_started_{};
   bool rx_control_{};

esphome/components/udp/packet_interface/__init__.py

@@ -0,0 +1,40 @@
+import esphome.codegen as cg
+from esphome.components import packet_interface
+from esphome.components.packet_interface import (
+    CONF_MAX_PACKET_SIZE,
+    new_packet_interface,
+    packet_interface_schema,
+)
+from esphome.const import CONF_ID
+from esphome.types import ConfigType
+
+from .. import CONF_UDP_ID, UDP_SCHEMA, udp_ns
+
+CODEOWNERS = ["@clydebarrow"]
+
+DEPENDENCIES = ["udp"]
+
+# Size of the receive buffer of the udp component
+MAX_PACKET_SIZE = 508
+
+UdpPacketInterface = udp_ns.class_(
+    "UdpPacketInterface",
+    packet_interface.PacketInterface,
+)
+
+CONFIG_SCHEMA = packet_interface_schema(
+    UdpPacketInterface, MAX_PACKET_SIZE, MAX_PACKET_SIZE
+).extend(UDP_SCHEMA)
+
+
+async def to_code(config: ConfigType) -> None:
+    udp_var = await cg.get_variable(config[CONF_UDP_ID])
+    cg.add(udp_var.set_should_listen())
+    # The udp component sends to its addresses through its broadcast socket
+    cg.add(udp_var.set_should_broadcast())
+    # The copy buffer's size is known here, so it is a static array rather than allocated at run time
+    tx_buffer = f"{config[CONF_ID].id}__tx_buffer"
+    cg.add_global(
+        cg.RawStatement(f"static uint8_t {tx_buffer}[{config[CONF_MAX_PACKET_SIZE]}];")
+    )
+    await new_packet_interface(config, udp_var, cg.RawExpression(tx_buffer))

esphome/components/udp/packet_interface/udp_packet_interface.cpp

@@ -0,0 +1,43 @@
+#include "udp_packet_interface.h"
+#ifdef USE_NETWORK
+#include "esphome/components/network/util.h"
+#include "esphome/core/log.h"
+
+namespace esphome::udp {
+
+using packet_interface::PacketBuffer;
+using packet_interface::PacketMetaData;
+
+ESPHOME_LOG_TAG(TAG, "udp.packet_interface");
+
+void UdpPacketInterface::setup() {
+  this->parent_->add_listener([this](std::span<const uint8_t> data) { this->receive_(data); });
+}
+
+void UdpPacketInterface::receive_(std::span<const uint8_t> data) {
+  if (data.size() > this->max_packet_size_) {
+    ESP_LOGV(TAG, "%s: Packet of %zu bytes is larger than %zu, dropped", this->name_, data.size(),
+             this->max_packet_size_);
+    return;
+  }
+  this->on_receive_from_interface_(PacketBuffer(data.data(), data.size()), {});
+}
+
+bool UdpPacketInterface::send_to_interface(const PacketBuffer &data, const PacketMetaData &meta_data) {
+  size_t size = data.size();
+  if (size > this->max_packet_size_) {
+    ESP_LOGW(TAG, "%s: Packet of %zu bytes is larger than %zu", this->name_, size, this->max_packet_size_);
+    return false;
+  }
+  if (!network::is_connected())
+    return false;
+  if (data.is_contiguous()) {
+    auto span = data.as_span();
+    return this->parent_->send_packet(span.data(), span.size());
+  }
+  data.copy_to(this->tx_buffer_.data(), size);
+  return this->parent_->send_packet(this->tx_buffer_.data(), size);
+}
+
+}  // namespace esphome::udp
+#endif

esphome/components/udp/packet_interface/udp_packet_interface.h

@@ -0,0 +1,37 @@
+#pragma once
+
+#include "esphome/core/defines.h"
+
+// udp_component.h declares nothing without USE_NETWORK
+#ifdef USE_NETWORK
+#include <span>
+
+#include "esphome/components/packet_interface/packet_interface.h"
+#include "../udp_component.h"
+
+namespace esphome::udp {
+
+/**
+ * A packet interface link over UDP: each packet is one datagram, sent to every address of the UDP component.
+ *
+ * Every datagram received on the listen port is passed up, from any sender, so on a shared network an addressing
+ * or encryption layer is needed to tell the peer's packets from others.
+ */
+class UdpPacketInterface : public packet_interface::PacketInterface {
+ public:
+  /// @param tx_buffer Joins packets split across buffers; its size is the largest packet, and it must outlive the link
+  UdpPacketInterface(UDPComponent *udp_component, std::span<uint8_t> tx_buffer)
+      : packet_interface::PacketInterface(tx_buffer.size()), parent_(udp_component), tx_buffer_(tx_buffer) {}
+
+  void setup() override;
+  bool send_to_interface(const packet_interface::PacketBuffer &data,
+                         const packet_interface::PacketMetaData &meta_data) override;
+
+ protected:
+  void receive_(std::span<const uint8_t> data);
+
+  UDPComponent *parent_;
+  const std::span<uint8_t> tx_buffer_;
+};
+}  // namespace esphome::udp
+#endif

esphome/components/udp/packet_transport/udp_transport.cpp

@@ -1,12 +1,9 @@
-#include "esphome/core/log.h"
 #include "esphome/core/application.h"
 #include "esphome/components/network/util.h"
 #include "udp_transport.h"
 
 namespace esphome::udp {
 
-ESPHOME_LOG_TAG(TAG, "udp_transport");
-
 bool UDPTransport::should_send() { return network::is_connected(); }
 void UDPTransport::setup() {
   PacketTransport::setup();

esphome/components/udp/udp_component.cpp

@@ -205,18 +205,25 @@ void UDPComponent::set_poll_warning_(PollStep step, const LogString *what) {
 }
 
 void UDPComponent::loop() {
-  if (this->should_listen_) {
-    std::array<uint8_t, MAX_PACKET_SIZE> buf;
-    for (;;) {
-      if (!this->listen_socket_->ready())
-        break;
-      auto len = this->listen_socket_->read(buf.data(), buf.size());
-      if (len <= 0)
-        break;
-      size_t packet_len = static_cast<size_t>(len);
-      ESP_LOGV(TAG, "Received packet of length %zu", packet_len);
-      this->packet_listeners_.call(std::span<const uint8_t>(buf.data(), packet_len));
+  if (!this->should_listen_) {
+    this->disable_loop();
+    return;
+  }
+  // One byte more than the largest packet, as a read cuts a longer datagram to fit and so cannot report it
+  std::array<uint8_t, MAX_PACKET_SIZE + 1> buf;
+  for (;;) {
+    if (!this->listen_socket_->ready())
+      break;
+    auto len = this->listen_socket_->read(buf.data(), buf.size());
+    if (len <= 0)
+      break;
+    size_t packet_len = static_cast<size_t>(len);
+    if (packet_len > MAX_PACKET_SIZE) {
+      ESP_LOGV(TAG, "Packet longer than %zu bytes dropped", MAX_PACKET_SIZE);
+      continue;
     }
+    ESP_LOGV(TAG, "Received packet of length %zu", packet_len);
+    this->packet_listeners_.call(std::span<const uint8_t>(buf.data(), packet_len));
   }
 }
 
@@ -239,9 +246,10 @@ void UDPComponent::dump_config() {
                 YESNO(this->should_broadcast_), YESNO(this->should_listen_));
 }
 
-void UDPComponent::send_packet(const uint8_t *data, size_t size) {
+bool UDPComponent::send_packet(const uint8_t *data, size_t size) {
   if (this->is_failed())
-    return;  // a send socket may be missing
+    return false;  // a send socket may be missing
+  bool sent = true;
   for (const auto &entry : this->sockaddrs_) {
 #ifdef USE_UDP_IPV6_SEND
     const bool v6 = entry.sa.sa_family == AF_INET6;
@@ -256,11 +264,23 @@ void UDPComponent::send_packet(const uint8_t *data, size_t size) {
     socket::UDPSendSocket *sock = this->broadcast_socket_.get();
     socklen_t sockaddr_size = sizeof(sockaddr_in);
 #endif
+    if (sock == nullptr) {
+      ESP_LOGW(TAG, "Broadcast socket not initialized");
+      return false;
+    }
     auto result = sock->sendto(data, size, 0, &entry.sa, sockaddr_size);
     if (result < 0) {
-      ESP_LOGW(TAG, "sendto() error %d", errno);
+      // lwIP refuses a packet with ENOMEM while the destination's ARP lookup is pending and its queue is full;
+      // the packet can be sent again later
+      if (errno == ENOMEM) {
+        ESP_LOGV(TAG, "sendto() out of memory");
+      } else {
+        ESP_LOGW(TAG, "sendto() error %d", errno);
+      }
+      sent = false;
     }
   }
+  return sent;
 }
 }  // namespace esphome::udp
 

esphome/components/udp/udp_component.h

@@ -35,8 +35,9 @@ class UDPComponent final : public Component {
   void setup() override;
   void loop() override;
   void dump_config() override;
-  void send_packet(const uint8_t *data, size_t size);
-  void send_packet(const std::vector<uint8_t> &buf) { this->send_packet(buf.data(), buf.size()); }
+  /// Returns false if the packet could not be sent to every destination.
+  bool send_packet(const uint8_t *data, size_t size);
+  bool send_packet(const std::vector<uint8_t> &buf) { return this->send_packet(buf.data(), buf.size()); }
   float get_setup_priority() const override { return setup_priority::AFTER_WIFI; };
 
  protected:
@@ -53,7 +54,7 @@ class UDPComponent final : public Component {
   bool network_poll_();
   void set_poll_warning_(PollStep step, const LogString *what);
 
-  CallbackManager<void(std::span<const uint8_t>)> packet_listeners_{};
+  LazyCallbackManager<void(std::span<const uint8_t>)> packet_listeners_{};
   std::unique_ptr<socket::UDPSendSocket> broadcast_socket_ = nullptr;
   std::unique_ptr<socket::UDPSocket> listen_socket_ = nullptr;
 #ifdef USE_UDP_IPV6_SEND

esphome/core/defines.h

@@ -257,6 +257,7 @@
 #define USE_OTA_STATE_LISTENER
 #define USE_OUTPUT
 #define USE_OUTPUT_FLOAT_POWER_SCALING
+#define USE_PACKET_INTERFACE_HDLC
 #define USE_POWER_SUPPLY
 // Only defined by key-lookup preference backends; the slot-based platforms
 // (esp8266, rp2040) never set it in generated builds, and their preferences

script/build_helpers.py

@@ -188,6 +188,8 @@ def load_component_yaml_configs(components: list[str], tests_dir: Path) -> dict:
 
     The ``esphome:`` key is special: its sub-keys are merged into the
     existing esphome config (e.g. to add ``areas:`` or ``devices:``).
+    A list, such as the entries of a platform component, is extended, so
+    several directories can each add their own entries to one key.
     Keys already present in the base config (e.g. ``host:``, ``logger:``)
     are protected by ``setdefault`` in the caller.
 
@@ -213,6 +215,9 @@ def load_component_yaml_configs(components: list[str], tests_dir: Path) -> dict:
                     for sub_key, sub_value in value.items():
                         esphome_extra.setdefault(sub_key, sub_value)
                     continue
+                if isinstance(value, list) and isinstance(merged.get(key), list):
+                    merged[key] = merged[key] + value
+                    continue
                 merged.setdefault(key, value)
     return merged
 

tests/components/packet_interface/__init__.py

@@ -0,0 +1,9 @@
+import esphome.codegen as cg
+from tests.testing_helpers import ComponentManifestOverride
+
+
+def override_manifest(manifest: ComponentManifestOverride) -> None:
+    async def to_code_testing(config: object) -> None:
+        cg.add_define("USE_PACKET_INTERFACE_HDLC")
+
+    manifest.to_code = to_code_testing

tests/components/packet_interface/benchmark.yaml

@@ -0,0 +1,11 @@
+uart:
+  port: /dev/ttyUSB0
+  baud_rate: 9600
+
+packet_interface:
+  - platform: uart
+    id: bridge_test_link
+
+packet_transport:
+  - platform: packet_interface
+    packet_interface: bridge_test_link

tests/components/packet_interface/common.yaml

@@ -0,0 +1,35 @@
+wifi:
+  ssid: MySSID
+  password: password1
+
+udp:
+  - id: packet_interface_udp
+
+packet_interface:
+  - platform: uart
+    id: packet_interface_uart
+    max_packet_size: 256
+    reliability:
+      timeout: 300ms
+      ack_delay: 50ms
+      max_queue_length: 3
+      max_retries: 4
+  - platform: udp
+    id: packet_interface_network
+    udp_id: packet_interface_udp
+    reliability:
+
+sensor:
+  - platform: template
+    id: packet_interface_sensor
+    lambda: return 1.0;
+
+packet_transport:
+  - platform: packet_interface
+    packet_interface: packet_interface_uart
+    sensors:
+      - packet_interface_sensor
+  - platform: packet_interface
+    packet_interface: packet_interface_network
+    sensors:
+      - packet_interface_sensor

tests/components/packet_interface/hdlc_reliability.cpp

@@ -0,0 +1,464 @@
+#include <gtest/gtest.h>
+#include <cstdint>
+#include <functional>
+#include <memory>
+#include <vector>
+#include "esphome/components/packet_interface/hdlc_reliability.h"
+#include "esphome/core/application.h"
+#include "esphome/core/hal.h"
+#include "esphome/core/helpers.h"
+
+namespace esphome::packet_interface::testing {
+
+// Copies a packet into a vector, for comparing in tests
+static std::vector<uint8_t> to_vector(const esphome::packet_interface::PacketBuffer &data) {
+  std::vector<uint8_t> result(data.size());
+  data.copy_to(result.data(), result.size());
+  return result;
+}
+
+using Frame = std::vector<uint8_t>;
+
+// A link layer that records what is sent, so a test can deliver it to the peer
+class MockLink : public PacketInterface {
+ public:
+  explicit MockLink(size_t max_packet_size = 64) : PacketInterface(max_packet_size) {}
+  bool send_to_interface(const PacketBuffer &data, const PacketMetaData &) override {
+    if (this->budget == 0) {
+      this->refused++;
+      return false;
+    }
+    this->budget--;
+    this->sent.push_back(to_vector(data));
+    return true;
+  }
+  void inject(const Frame &frame) { this->on_receive_from_interface_(PacketBuffer(frame), {}); }
+
+  std::vector<Frame> sent;
+  size_t budget{SIZE_MAX};  // frames accepted before the link refuses, like a full network stack
+  size_t refused{0};
+};
+
+class TestHdlc : public HdlcReliability {
+ public:
+  using HdlcReliability::HdlcReliability;
+  using HdlcReliability::on_timeout_;
+  using HdlcReliability::outstanding_;
+};
+
+struct Peer {
+  explicit Peer(uint8_t queue_length = 4) {
+    this->hdlc = std::make_unique<TestHdlc>(&this->link);
+    this->hdlc->set_max_queue_length(queue_length);
+    this->hdlc->set_max_retries(3);
+    this->hdlc->setup();
+    this->hdlc->add_packet_interface_listener(
+        [this](const PacketBuffer &data, const PacketMetaData &) { this->received.push_back(to_vector(data)); });
+    this->hdlc->add_on_session_state_callback([this](bool connected) { this->states.push_back(connected); });
+  }
+  bool send(const Frame &data) { return this->hdlc->send_to_interface(PacketBuffer(data), {}); }
+
+  MockLink link;
+  std::unique_ptr<TestHdlc> hdlc;
+  std::vector<Frame> received;
+  std::vector<bool> states;
+};
+
+// Returns true to drop a frame on its way from one peer to the other
+using DropFilter = std::function<bool(const Frame &)>;
+
+static bool is_info(const Frame &frame) { return (frame[0] & 1) == 0; }
+static bool is_ack(const Frame &frame) { return (frame[0] & 0x0F) == 0x01; }
+
+// Runs a layer's loop only while it has asked for it, as the main loop does
+static void run_loop(TestHdlc &hdlc) {
+  if (!hdlc.is_idle())
+    hdlc.loop();
+}
+
+// Move frames between the peers and run their loops until nothing more is sent
+static void pump(Peer &a, Peer &b, const DropFilter &drop_a_to_b = nullptr, const DropFilter &drop_b_to_a = nullptr) {
+  for (int i = 0; i != 50; i++) {
+    run_loop(*a.hdlc);
+    run_loop(*b.hdlc);
+    if (a.link.sent.empty() && b.link.sent.empty())
+      return;
+    auto from_a = std::move(a.link.sent);
+    auto from_b = std::move(b.link.sent);
+    a.link.sent.clear();
+    b.link.sent.clear();
+    for (auto &frame : from_a) {
+      if (!drop_a_to_b || !drop_a_to_b(frame))
+        b.link.inject(frame);
+    }
+    for (auto &frame : from_b) {
+      if (!drop_b_to_a || !drop_b_to_a(frame))
+        a.link.inject(frame);
+    }
+  }
+  FAIL() << "Peers did not go quiet";
+}
+
+static Frame make_frame(uint8_t control, const Frame &payload) {
+  Frame frame{control};
+  frame.insert(frame.end(), payload.begin(), payload.end());
+  uint16_t crc = crc16(frame.data(), frame.size());
+  frame.push_back(crc & 0xFF);
+  frame.push_back(crc >> 8);
+  return frame;
+}
+
+// Each test replaces App with a fresh one; the retransmit timer needs its scheduler
+class HdlcReliabilityTest : public ::testing::Test {
+ protected:
+  void SetUp() override {
+    App.~Application();
+    new (&App) Application();
+    static char name[] = "hdlc-tests";
+    static char friendly_name[] = "";
+    App.pre_setup(name, sizeof(name) - 1, friendly_name, 0);
+  }
+  void TearDown() override {
+    App.~Application();
+    new (&App) Application();  // later tests and the test listener use App
+  }
+};
+
+TEST_F(HdlcReliabilityTest, MaxPacketSizeAllowsForOverhead) {
+  Peer a;
+  EXPECT_EQ(a.hdlc->get_send_capacity(), 4);
+  EXPECT_EQ(a.hdlc->get_max_packet_size(), 64 - HdlcReliability::FRAME_OVERHEAD);
+  EXPECT_EQ(a.link.top(), a.hdlc.get());
+  EXPECT_EQ(a.hdlc->get_capabilities(), CAPABILITY_RELIABILITY);
+}
+
+TEST_F(HdlcReliabilityTest, ResetHandshake) {
+  Peer a, b;
+  a.hdlc->loop();
+  ASSERT_EQ(a.link.sent.size(), 1);
+  EXPECT_EQ(a.link.sent[0], make_frame(0x2F, {}));  // SABM
+  pump(a, b);
+  EXPECT_TRUE(a.hdlc->is_connected());
+  EXPECT_TRUE(b.hdlc->is_connected());
+}
+
+TEST_F(HdlcReliabilityTest, RepeatedSabmBeforeNumberedFramesKeepsQueue) {
+  Peer a, b;
+  pump(a, b);
+  // A frame is queued and sent, but has not reached A, so A has sent no numbered frame
+  ASSERT_TRUE(b.send({0x42}));
+  auto held = std::move(b.link.sent);
+  b.link.sent.clear();
+  EXPECT_EQ(b.hdlc->get_send_capacity(), 3);
+
+  // A repeats its SABM because it did not hear the UA; that is not a restart
+  b.link.inject(make_frame(0x2F, {}));  // SABM
+  EXPECT_TRUE(b.hdlc->is_connected());
+  EXPECT_TRUE(b.states.empty());              // no session lost reported
+  EXPECT_EQ(b.hdlc->get_send_capacity(), 3);  // the queued frame was kept
+  ASSERT_FALSE(b.link.sent.empty());
+  EXPECT_EQ(b.link.sent[0], make_frame(0x63, {}));  // UA, then the frame is sent again
+
+  // The frame is still delivered when it reaches A
+  for (auto &frame : held)
+    a.link.inject(frame);
+  EXPECT_EQ(a.received, std::vector<Frame>{{0x42}});
+}
+
+TEST_F(HdlcReliabilityTest, SabmAfterNumberedFramesIsARestart) {
+  Peer a, b;
+  pump(a, b);
+  // B has heard a numbered frame, so a SABM now means A has started again
+  ASSERT_TRUE(a.send({0x10}));
+  pump(a, b);
+  b.link.inject(make_frame(0x2F, {}));  // SABM
+  EXPECT_TRUE(b.hdlc->is_connected());
+  EXPECT_EQ(b.states, std::vector<bool>{false});
+}
+
+TEST_F(HdlcReliabilityTest, QueuedBeforeConnectIsSentAfter) {
+  Peer a, b;
+  ASSERT_TRUE(a.send({0x01}));
+  ASSERT_TRUE(a.send({0x02}));
+  pump(a, b);
+  EXPECT_EQ(b.received, (std::vector<Frame>{{0x01}, {0x02}}));
+}
+
+TEST_F(HdlcReliabilityTest, DeliversInOrderBothWays) {
+  Peer a, b;
+  pump(a, b);
+  a.send({0x10});
+  b.send({0x20});
+  a.send({0x11});
+  pump(a, b);
+  EXPECT_EQ(b.received, (std::vector<Frame>{{0x10}, {0x11}}));
+  EXPECT_EQ(a.received, (std::vector<Frame>{{0x20}}));
+}
+
+TEST_F(HdlcReliabilityTest, SequenceNumbersWrap) {
+  Peer a(3), b(3);
+  pump(a, b);
+  std::vector<Frame> expected;
+  for (uint8_t i = 0; i != 20; i++) {
+    expected.push_back({i, static_cast<uint8_t>(i * 3)});
+    ASSERT_TRUE(a.send(expected.back()));
+    if (i % 2 == 1)
+      pump(a, b);
+  }
+  pump(a, b);
+  EXPECT_EQ(b.received, expected);
+}
+
+TEST_F(HdlcReliabilityTest, GapRecoveredByReject) {
+  Peer a, b;
+  pump(a, b);
+  bool dropped = false;
+  a.send({0x01});
+  a.send({0x02});
+  a.send({0x03});
+  pump(a, b, [&dropped](const Frame &frame) {
+    if (dropped || !is_info(frame))
+      return false;
+    dropped = true;
+    return true;
+  });
+  EXPECT_EQ(b.received, (std::vector<Frame>{{0x01}, {0x02}, {0x03}}));
+}
+
+TEST_F(HdlcReliabilityTest, LossRecoveredByTimeout) {
+  Peer a, b;
+  pump(a, b);
+  a.send({0x42});
+  pump(a, b, [](const Frame &frame) { return is_info(frame); });
+  EXPECT_TRUE(b.received.empty());
+  a.hdlc->on_timeout_();
+  pump(a, b);
+  EXPECT_EQ(b.received, (std::vector<Frame>{{0x42}}));
+}
+
+TEST_F(HdlcReliabilityTest, LostAckDoesNotDuplicate) {
+  Peer a, b;
+  pump(a, b);
+  a.send({0x42});
+  pump(a, b, nullptr, [](const Frame &frame) { return is_ack(frame); });
+  ASSERT_EQ(b.received.size(), 1);
+  a.hdlc->on_timeout_();
+  pump(a, b);
+  EXPECT_EQ(b.received.size(), 1);
+  // The resend was acknowledged, so the full queue is available again
+  for (int i = 0; i != 4; i++)
+    EXPECT_TRUE(a.send({0x01}));
+}
+
+TEST_F(HdlcReliabilityTest, QueueFull) {
+  Peer a(2), b(2);
+  pump(a, b);
+  EXPECT_TRUE(a.send({0x01}));
+  EXPECT_TRUE(a.send({0x02}));
+  EXPECT_FALSE(a.send({0x03}));
+}
+
+TEST_F(HdlcReliabilityTest, OversizedPacketRejected) {
+  Peer a;
+  EXPECT_FALSE(a.send(Frame(a.hdlc->get_max_packet_size() + 1)));
+}
+
+TEST_F(HdlcReliabilityTest, CrcErrorDropped) {
+  Peer a, b;
+  pump(a, b);
+  Frame frame = make_frame(0x00, {0x55});  // I-frame N(S)=0 N(R)=0
+  frame[1] ^= 0xFF;
+  b.link.inject(frame);
+  EXPECT_TRUE(b.received.empty());
+  b.link.inject(make_frame(0x00, {0x55}));
+  EXPECT_EQ(b.received, (std::vector<Frame>{{0x55}}));
+}
+
+TEST_F(HdlcReliabilityTest, RetriesExhaustedResetsLink) {
+  Peer a, b;
+  pump(a, b);
+  // One frame is delivered first, so b can tell a reset from a repeated SABM
+  ASSERT_TRUE(a.send({0x00}));
+  pump(a, b);
+  ASSERT_EQ(b.received, std::vector<Frame>{{0x00}});
+  a.send({0x01});
+  pump(a, b, [](const Frame &frame) { return is_info(frame); });
+  for (int i = 0; i != 4; i++) {
+    a.hdlc->on_timeout_();
+    pump(a, b, [](const Frame &frame) { return is_info(frame); });
+  }
+  // The unacknowledged frame was discarded and the link was reset, which both report as data lost
+  EXPECT_EQ(b.received, std::vector<Frame>{{0x00}});
+  EXPECT_TRUE(a.hdlc->is_connected());
+  EXPECT_EQ(a.states, std::vector<bool>{false});
+  EXPECT_EQ(b.states, std::vector<bool>{false});
+  a.send({0x02});
+  pump(a, b);
+  EXPECT_EQ(b.received, (std::vector<Frame>{{0x00}, {0x02}}));
+}
+
+TEST_F(HdlcReliabilityTest, PeerRestart) {
+  Peer a;
+  auto b = std::make_unique<Peer>();
+  pump(a, *b);
+  a.send({0x01});
+  pump(a, *b);
+  // The peer restarts with fresh sequence numbers
+  b = std::make_unique<Peer>();
+  pump(a, *b);
+  a.send({0x02});
+  b->send({0x03});
+  pump(a, *b);
+  EXPECT_EQ(b->received, (std::vector<Frame>{{0x02}}));
+  EXPECT_EQ(a.received, (std::vector<Frame>{{0x03}}));
+  // The restarted peer's reset discarded what a had not yet had acknowledged
+  EXPECT_EQ(a.states, std::vector<bool>{false});
+  EXPECT_TRUE(b->states.empty());
+}
+
+// Waits past the retry after a refused send, servicing timers as the main loop does
+static void run_send_retry() {
+  const uint32_t start = millis();
+  while (millis() - start < 60) {
+    App.scheduler.call(millis());
+    delay(1);
+  }
+  App.scheduler.call(millis());
+}
+
+TEST_F(HdlcReliabilityTest, RefusedFramesSentAgainWithoutTimeout) {
+  Peer a, b;
+  // Only the retry of a refused send can fire while the test runs, not a retransmit
+  a.hdlc->set_ack_timeout(10000);
+  b.hdlc->set_ack_timeout(10000);
+  for (uint8_t i = 0; i != 3; i++)
+    ASSERT_TRUE(a.send({i}));
+  a.link.budget = 3;  // SABM, UA to the peer's SABM, and the first queued frame
+  pump(a, b);
+  EXPECT_GE(a.link.refused, 1);
+  EXPECT_EQ(b.received, (std::vector<Frame>{{0}}));
+  a.link.budget = SIZE_MAX;  // the lower layer accepts again, as when a radio stops receiving
+  // The layer waits for its retry rather than running every loop
+  pump(a, b);
+  EXPECT_EQ(b.received, (std::vector<Frame>{{0}}));
+  run_send_retry();
+  pump(a, b);
+  EXPECT_EQ(b.received, (std::vector<Frame>{{0}, {1}, {2}}));
+  EXPECT_EQ(a.hdlc->outstanding_(), 0);
+}
+
+TEST_F(HdlcReliabilityTest, RefusedAckSentAgain) {
+  Peer a, b;
+  a.hdlc->set_ack_timeout(10000);
+  b.hdlc->set_ack_timeout(10000);
+  pump(a, b);
+  a.send({1});
+  for (auto &frame : a.link.sent)
+    b.link.inject(frame);
+  a.link.sent.clear();
+  b.link.budget = 0;
+  b.hdlc->loop();
+  EXPECT_TRUE(b.link.sent.empty());
+  b.link.budget = SIZE_MAX;
+  pump(a, b);
+  EXPECT_EQ(a.hdlc->outstanding_(), 1);  // the RR waits for the retry
+  run_send_retry();
+  pump(a, b);
+  EXPECT_EQ(a.hdlc->outstanding_(), 0);
+}
+
+TEST_F(HdlcReliabilityTest, AckDelayLetsReplyCarryAck) {
+  Peer a, b;
+  b.hdlc->set_ack_delay(100);
+  pump(a, b);
+  a.send({1});
+  for (auto &frame : a.link.sent)
+    b.link.inject(frame);
+  a.link.sent.clear();
+  b.hdlc->loop();
+  EXPECT_TRUE(b.link.sent.empty());  // no RR yet
+  b.send({2});
+  ASSERT_EQ(b.link.sent.size(), 1);
+  EXPECT_TRUE(is_info(b.link.sent[0]));
+  EXPECT_EQ(b.link.sent[0][0] >> 5, 1);  // N(R) acknowledges the frame from a
+  b.link.sent.clear();
+  b.hdlc->loop();
+  EXPECT_TRUE(b.link.sent.empty());  // the RR is no longer owed
+}
+
+TEST_F(HdlcReliabilityTest, MaxRetriesOf255ResetsLink) {
+  Peer a, b;
+  a.hdlc->set_max_retries(255);
+  pump(a, b);
+  a.send({0x01});
+  a.link.sent.clear();
+  for (int i = 0; i != 255; i++) {
+    a.hdlc->on_timeout_();
+    a.link.sent.clear();
+  }
+  EXPECT_TRUE(a.states.empty());
+  a.hdlc->on_timeout_();
+  EXPECT_EQ(a.states, std::vector<bool>{false});
+}
+
+TEST_F(HdlcReliabilityTest, OversizedFrameDropped) {
+  Peer a, b;
+  pump(a, b);
+  // An I-frame, N(S) 0 and N(R) 0, one byte larger than this layer's packets
+  b.link.inject(make_frame(0x00, Frame(b.hdlc->get_max_packet_size() + 1, 0x55)));
+  EXPECT_TRUE(b.received.empty());
+  b.link.inject(make_frame(0x00, Frame(b.hdlc->get_max_packet_size(), 0x55)));
+  EXPECT_EQ(b.received.size(), 1);
+}
+
+TEST_F(HdlcReliabilityTest, LinkTooSmallFailsSetup) {
+  MockLink link(HdlcReliability::FRAME_OVERHEAD);
+  TestHdlc hdlc(&link);
+  EXPECT_EQ(hdlc.get_max_packet_size(), 0);
+  hdlc.setup();
+  EXPECT_TRUE(hdlc.is_failed());
+  Frame packet{1};
+  EXPECT_FALSE(hdlc.send_to_interface(PacketBuffer(packet), {}));
+  EXPECT_EQ(hdlc.get_send_capacity(), 0);
+}
+
+TEST_F(HdlcReliabilityTest, AckDelayTimerSendsAck) {
+  Peer a, b;
+  b.hdlc->set_ack_delay(5);
+  pump(a, b);
+  a.send({1});
+  for (auto &frame : a.link.sent)
+    b.link.inject(frame);
+  a.link.sent.clear();
+  b.hdlc->loop();
+  EXPECT_TRUE(b.link.sent.empty());
+  delay(10);
+  App.scheduler.call(millis());
+  b.hdlc->loop();
+  ASSERT_EQ(b.link.sent.size(), 1);
+  EXPECT_TRUE(is_ack(b.link.sent[0]));
+  EXPECT_EQ(b.link.sent[0][0] >> 5, 1);  // N(R) acknowledges the frame from a
+}
+
+TEST_F(HdlcReliabilityTest, RefusedRejectFallsBackToAck) {
+  Peer a, b;
+  pump(a, b);
+  a.send({1});
+  a.send({2});
+  ASSERT_EQ(a.link.sent.size(), 2);
+  // The first frame is lost, and the REJ for the gap is refused
+  b.link.budget = 0;
+  b.link.inject(a.link.sent[1]);
+  a.link.sent.clear();
+  EXPECT_EQ(b.link.refused, 1);
+  b.link.budget = SIZE_MAX;
+  b.hdlc->loop();
+  ASSERT_EQ(b.link.sent.size(), 1);
+  EXPECT_TRUE(is_ack(b.link.sent[0]));
+  EXPECT_EQ(b.link.sent[0][0] >> 5, 0);
+  a.hdlc->on_timeout_();
+  pump(a, b);
+  EXPECT_EQ(b.received, (std::vector<Frame>{{1}, {2}}));
+}
+
+}  // namespace esphome::packet_interface::testing

tests/components/packet_interface/packet_buffer.cpp

@@ -0,0 +1,238 @@
+#include <gtest/gtest.h>
+#include <vector>
+#include <cstdint>
+#include "esphome/components/packet_interface/packet_buffer.h"
+
+namespace esphome::packet_interface::testing {
+
+// Copies a packet into a vector, for comparing in tests
+static std::vector<uint8_t> to_vector(const esphome::packet_interface::PacketBuffer &data) {
+  std::vector<uint8_t> result(data.size());
+  data.copy_to(result.data(), result.size());
+  return result;
+}
+
+// Test default constructor
+TEST(PacketBufferTest, DefaultConstructor) {
+  PacketBuffer buffer;
+  EXPECT_EQ(buffer.size(), 0);
+  EXPECT_TRUE(buffer.empty());
+}
+
+// Test single buffer constructor
+TEST(PacketBufferTest, SingleBufferConstructor) {
+  uint8_t data[] = {0x01, 0x02, 0x03, 0x04};
+  PacketBuffer buffer(data, 4);
+  EXPECT_EQ(buffer.size(), 4);
+  EXPECT_FALSE(buffer.empty());
+  EXPECT_EQ(buffer[0], 0x01);
+  EXPECT_EQ(buffer[3], 0x04);
+}
+
+// Test vector constructor
+TEST(PacketBufferTest, VectorConstructor) {
+  std::vector<uint8_t> vec = {0x10, 0x20, 0x30};
+  PacketBuffer buffer(vec);
+  EXPECT_EQ(buffer.size(), 3);
+  EXPECT_EQ(buffer[0], 0x10);
+  EXPECT_EQ(buffer[1], 0x20);
+  EXPECT_EQ(buffer[2], 0x30);
+}
+
+// Test pre and post buffer constructor
+TEST(PacketBufferTest, PrePostConstructor) {
+  uint8_t pre[] = {0x01, 0x02};
+  uint8_t post[] = {0x03, 0x04, 0x05};
+  PacketBuffer buffer(pre, 2, post, 3);
+  EXPECT_EQ(buffer.size(), 5);
+  EXPECT_EQ(buffer[0], 0x01);
+  EXPECT_EQ(buffer[1], 0x02);
+  EXPECT_EQ(buffer[2], 0x03);
+  EXPECT_EQ(buffer[3], 0x04);
+  EXPECT_EQ(buffer[4], 0x05);
+}
+
+// Test pre, mid, and post buffer constructor
+TEST(PacketBufferTest, PreMidPostConstructor) {
+  uint8_t pre[] = {0x01};
+  std::vector<uint8_t> mid_vec = {0x02, 0x03, 0x04};
+  PacketBuffer mid_buffer(mid_vec);
+  uint8_t post[] = {0x05, 0x06};
+
+  PacketBuffer buffer(pre, 1, &mid_buffer, post, 2);
+  EXPECT_EQ(buffer.size(), 6);
+  EXPECT_EQ(buffer[0], 0x01);
+  EXPECT_EQ(buffer[1], 0x02);
+  EXPECT_EQ(buffer[2], 0x03);
+  EXPECT_EQ(buffer[3], 0x04);
+  EXPECT_EQ(buffer[4], 0x05);
+  EXPECT_EQ(buffer[5], 0x06);
+}
+
+// Test nested mid buffers
+TEST(PacketBufferTest, NestedMidBuffers) {
+  uint8_t data1[] = {0x01};
+  uint8_t data2[] = {0x02, 0x03};
+  uint8_t data3[] = {0x04};
+
+  PacketBuffer inner(data2, 2);
+  PacketBuffer middle(data1, 1, &inner, data3, 1);
+
+  uint8_t pre[] = {0x00};
+  uint8_t post[] = {0x05};
+  PacketBuffer outer(pre, 1, &middle, post, 1);
+
+  EXPECT_EQ(outer.size(), 6);
+  EXPECT_EQ(outer[0], 0x00);
+  EXPECT_EQ(outer[1], 0x01);
+  EXPECT_EQ(outer[2], 0x02);
+  EXPECT_EQ(outer[3], 0x03);
+  EXPECT_EQ(outer[4], 0x04);
+  EXPECT_EQ(outer[5], 0x05);
+}
+
+// Test indexing operator
+TEST(PacketBufferTest, IndexingOperator) {
+  uint8_t data[] = {0xAA, 0xBB, 0xCC, 0xDD};
+  PacketBuffer buffer(data, 4);
+  EXPECT_EQ(buffer[0], 0xAA);
+  EXPECT_EQ(buffer[1], 0xBB);
+  EXPECT_EQ(buffer[2], 0xCC);
+  EXPECT_EQ(buffer[3], 0xDD);
+}
+
+// Test copy_to method
+TEST(PacketBufferTest, CopyTo) {
+  uint8_t data[] = {0x01, 0x02, 0x03, 0x04, 0x05};
+  PacketBuffer buffer(data, 5);
+
+  uint8_t dest[5] = {0};
+  size_t copied = buffer.copy_to(dest, 5);
+
+  EXPECT_EQ(copied, 5);
+  for (int i = 0; i < 5; i++) {
+    EXPECT_EQ(dest[i], data[i]);
+  }
+}
+
+// Test copy_to with offset
+TEST(PacketBufferTest, CopyToWithOffset) {
+  uint8_t data[] = {0x01, 0x02, 0x03, 0x04, 0x05};
+  PacketBuffer buffer(data, 5);
+
+  uint8_t dest[3] = {0};
+  size_t copied = buffer.copy_to(dest, 3, 2);  // Copy 3 bytes starting from offset 2
+
+  EXPECT_EQ(copied, 3);
+  EXPECT_EQ(dest[0], 0x03);
+  EXPECT_EQ(dest[1], 0x04);
+  EXPECT_EQ(dest[2], 0x05);
+}
+
+// Test copy_to with partial copy
+TEST(PacketBufferTest, CopyToPartial) {
+  uint8_t data[] = {0x01, 0x02, 0x03};
+  PacketBuffer buffer(data, 3);
+
+  uint8_t dest[5] = {0};
+  size_t copied = buffer.copy_to(dest, 5);  // Request more than available
+
+  EXPECT_EQ(copied, 3);  // Only 3 bytes copied
+}
+
+// Test copy_to from composite buffer
+TEST(PacketBufferTest, CopyToComposite) {
+  uint8_t pre[] = {0x01, 0x02};
+  uint8_t mid[] = {0x03, 0x04, 0x05};
+  uint8_t post[] = {0x06};
+
+  PacketBuffer mid_buffer(mid, 3);
+  PacketBuffer buffer(pre, 2, &mid_buffer, post, 1);
+
+  uint8_t dest[6] = {0};
+  size_t copied = buffer.copy_to(dest, 6);
+
+  EXPECT_EQ(copied, 6);
+  EXPECT_EQ(dest[0], 0x01);
+  EXPECT_EQ(dest[1], 0x02);
+  EXPECT_EQ(dest[2], 0x03);
+  EXPECT_EQ(dest[3], 0x04);
+  EXPECT_EQ(dest[4], 0x05);
+  EXPECT_EQ(dest[5], 0x06);
+}
+
+// Test copying from an offset past the mid buffer
+TEST(PacketBufferTest, CopyToOffsetPastMid) {
+  uint8_t pre[] = {0x01, 0x02};
+  uint8_t mid_data[] = {0x03};
+  uint8_t post[] = {0x04, 0x05, 0x06};
+  PacketBuffer mid(mid_data, 1);
+  PacketBuffer buffer(pre, 2, &mid, post, 3);
+
+  uint8_t dest[4]{};
+  ASSERT_EQ(buffer.copy_to(dest, 4, 4), 2);
+  EXPECT_EQ(dest[0], 0x05);
+  EXPECT_EQ(dest[1], 0x06);
+}
+
+// Test single span access
+TEST(PacketBufferTest, ContiguousSpan) {
+  uint8_t data[] = {0x10, 0x20, 0x30, 0x40};
+  PacketBuffer buffer(data, 4);
+
+  ASSERT_TRUE(buffer.is_contiguous());
+  auto span = buffer.as_span();
+  EXPECT_EQ(span.data(), data);
+  EXPECT_EQ(span.size(), 4);
+
+  uint8_t post[] = {0x50};
+  PacketBuffer split(data, 4, post, 1);
+  EXPECT_FALSE(split.is_contiguous());
+
+  PacketBuffer nested(nullptr, 0, &buffer, nullptr, 0);
+  EXPECT_FALSE(nested.is_contiguous());
+}
+
+// Test indexing past the end
+TEST(PacketBufferTest, IndexPastEnd) {
+  uint8_t pre[] = {0x01};
+  uint8_t post[] = {0x02};
+  PacketBuffer buffer(pre, 1, post, 1);
+  EXPECT_EQ(buffer[1], 0x02);
+  EXPECT_EQ(buffer[2], 0);
+  EXPECT_EQ(PacketBuffer()[0], 0);
+}
+
+// Test empty buffer operations
+TEST(PacketBufferTest, EmptyBuffer) {
+  PacketBuffer buffer;
+
+  EXPECT_TRUE(buffer.empty());
+  EXPECT_EQ(buffer.size(), 0);
+
+  uint8_t dest[10] = {0xFF};
+  size_t copied = buffer.copy_to(dest, 10);
+  EXPECT_EQ(copied, 0);
+  EXPECT_EQ(dest[0], 0xFF);  // Unchanged
+
+  std::vector<uint8_t> vec = to_vector(buffer);
+  EXPECT_EQ(vec.size(), 0);
+}
+
+// Test large buffer
+TEST(PacketBufferTest, LargeBuffer) {
+  std::vector<uint8_t> large_vec(1000);
+  for (size_t i = 0; i < large_vec.size(); i++) {
+    large_vec[i] = static_cast<uint8_t>(i % 256);
+  }
+
+  PacketBuffer buffer(large_vec);
+
+  EXPECT_EQ(buffer.size(), 1000);
+  EXPECT_EQ(buffer[0], 0);
+  EXPECT_EQ(buffer[255], 255);
+  EXPECT_EQ(buffer[256], 0);
+  EXPECT_EQ(buffer[999], 231);  // 999 % 256 = 231
+}
+
+}  // namespace esphome::packet_interface::testing

tests/components/packet_interface/packet_interface_transport.cpp

@@ -0,0 +1,92 @@
+#include <gtest/gtest.h>
+#include <cstdint>
+#include <cstring>
+#include <vector>
+#include "esphome/components/packet_interface/packet_transport/packet_interface_transport.h"
+#include "esphome/core/application.h"
+
+namespace esphome::packet_interface::transport_testing {
+
+using Packet = std::vector<uint8_t>;
+
+// A link layer that records what is sent, and passes injected packets to its listeners
+class FakeInterface : public PacketInterface {
+ public:
+  explicit FakeInterface(size_t max_packet_size = 512) : PacketInterface(max_packet_size) {}
+  bool send_to_interface(const PacketBuffer &data, const PacketMetaData &) override {
+    Packet packet(data.size());
+    data.copy_to(packet.data(), packet.size());
+    this->sent.push_back(packet);
+    return true;
+  }
+  void deliver(const PacketBuffer &data) { this->on_receive_from_interface_(data, {}); }
+
+  std::vector<Packet> sent;
+};
+
+// A layer stacked on a link, which the bridge must use in place of the link
+class FakeLayer : public FakeInterface {
+ public:
+  explicit FakeLayer(PacketInterface *lower) : FakeInterface(lower->get_max_packet_size()) {
+    this->stack_on_(lower, CAPABILITY_ENCRYPTION);
+  }
+};
+
+class TestBridge : public PacketInterfaceTransport {
+ public:
+  using PacketInterfaceTransport::PacketInterfaceTransport;
+  using PacketInterfaceTransport::send_packet;
+  using packet_transport::PacketTransport::ping_keys_;
+};
+
+// A packet_transport ping packet; with an encryption key set, process_() stores the sender's key
+static Packet ping_packet(const char *hostname, uint32_t key) {
+  Packet packet{0x48, 0x50, static_cast<uint8_t>(strlen(hostname))};
+  packet.insert(packet.end(), hostname, hostname + strlen(hostname));
+  for (int shift = 0; shift != 32; shift += 8)
+    packet.push_back(static_cast<uint8_t>(key >> shift));
+  return packet;
+}
+
+// Each test replaces App with a fresh one, which the transport's setup() reads the device name from
+class PacketInterfaceTransportTest : public ::testing::Test {
+ protected:
+  void SetUp() override {
+    App.~Application();
+    new (&App) Application();
+    static char name[] = "bridge-tests";
+    static char friendly_name[] = "";
+    App.pre_setup(name, sizeof(name) - 1, friendly_name, 0);
+    this->bridge_.set_encryption_key(std::vector<uint8_t>(32, 0xAA));
+    this->bridge_.setup();
+  }
+  void TearDown() override {
+    App.~Application();
+    new (&App) Application();  // later tests and the test listener use App
+  }
+
+  FakeInterface link_;
+  FakeLayer layer_{&this->link_};
+  TestBridge bridge_{&this->link_};
+};
+
+TEST_F(PacketInterfaceTransportTest, SendsThroughTopOfStack) {
+  this->bridge_.send_packet({1, 2, 3});
+  EXPECT_EQ(this->layer_.sent, (std::vector<Packet>{{1, 2, 3}}));
+  EXPECT_TRUE(this->link_.sent.empty());
+}
+
+TEST_F(PacketInterfaceTransportTest, PacketInOneBufferReachesTransport) {
+  Packet ping = ping_packet("requester", 0xDEADBEEF);
+  this->layer_.deliver(PacketBuffer(ping));
+  ASSERT_EQ(this->bridge_.ping_keys_.size(), 1u);
+  EXPECT_EQ(this->bridge_.ping_keys_["requester"], 0xDEADBEEFu);
+}
+
+TEST_F(PacketInterfaceTransportTest, PacketSplitAcrossBuffersDropped) {
+  Packet ping = ping_packet("requester", 0xDEADBEEF);
+  this->layer_.deliver(PacketBuffer(ping.data(), 4, ping.data() + 4, ping.size() - 4));
+  EXPECT_TRUE(this->bridge_.ping_keys_.empty());
+}
+
+}  // namespace esphome::packet_interface::transport_testing

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

@@ -0,0 +1,3 @@
+packages:
+  uart: !include ../../test_build_components/common/uart/esp32-idf.yaml
+  packet_interface: !include common.yaml

tests/components/packet_transport/common.yaml

@@ -3,12 +3,14 @@ wifi:
   password: password1
 
 udp:
-  listen_address: 239.0.60.53
-  addresses: ["239.0.60.53"]
+  - id: transport_udp_component
+    listen_address: 239.0.60.53
+    addresses: ["239.0.60.53"]
 
 packet_transport:
   - platform: udp
     id: transport_udp
+    udp_id: transport_udp_component
     update_interval: 5s
     encryption: "our key goes here"
     rolling_code_enable: true

tests/components/uart/__init__.py

@@ -0,0 +1,6 @@
+from tests.testing_helpers import ComponentManifestOverride
+
+
+def override_manifest(manifest: ComponentManifestOverride) -> None:
+    # benchmark.yaml configures a uart packet_interface, whose to_code waits on the uart bus variable.
+    manifest.enable_codegen()

tests/components/uart/benchmark.yaml

@@ -0,0 +1,6 @@
+packet_interface:
+  - platform: uart
+
+uart:
+  port: /dev/ttyUSB0
+  baud_rate: 9600

tests/components/uart/common.h

@@ -25,7 +25,10 @@ class MockUARTComponent : public UARTComponent {
   // consider using StaticVector or FixedVector from esphome/core/helpers.h instead.
   std::vector<uint8_t> written_data;
 
-  void write_array(const uint8_t *data, size_t len) override { written_data.assign(data, data + len); }
+  void write_array(const uint8_t *data, size_t len) override {
+    written_data.insert(written_data.end(), data, data + len);
+  }
+  void clear() { written_data.clear(); }
 
   MOCK_METHOD(bool, read_array, (uint8_t * data, size_t len), (override));
   MOCK_METHOD(bool, peek_byte, (uint8_t * data), (override));

tests/components/uart/uart_packet_interface.cpp

@@ -0,0 +1,392 @@
+#include <gtest/gtest.h>
+#include <gmock/gmock.h>
+#include <vector>
+#include <cstdint>
+#include "esphome/components/uart/packet_interface/uart_packet_interface.h"
+#include "esphome/components/packet_interface/packet_buffer.h"
+#include "esphome/components/uart/uart_component.h"
+#include "common.h"
+
+namespace esphome::uart::testing {
+
+// Copies a packet into a vector, for comparing in tests
+static std::vector<uint8_t> to_vector(const esphome::packet_interface::PacketBuffer &data) {
+  std::vector<uint8_t> result(data.size());
+  data.copy_to(result.data(), result.size());
+  return result;
+}
+
+using packet_interface::PacketBuffer;
+using packet_interface::PacketMetaData;
+
+// Test fixture
+class UartPacketInterfaceTest : public ::testing::Test {
+ protected:
+  MockUARTComponent uart_{};
+  // As large as the default max_packet_size; tests only make it smaller
+  uint8_t rx_buffer_[512]{};
+  UartPacketInterface interface_{this->rx_buffer_};
+  std::vector<std::vector<uint8_t>> received_packets_;
+
+  void SetUp() override {
+    received_packets_.clear();
+    interface_.set_uart_parent(&uart_);
+    interface_.setup();
+
+    interface_.add_packet_interface_listener(
+        [this](const PacketBuffer &data, const PacketMetaData &meta) { received_packets_.push_back(to_vector(data)); });
+  }
+};
+
+// Feed bytes to the interface through the mocked UART and run its loop
+static void feed(MockUARTComponent &uart, UartPacketInterface &interface, const std::vector<uint8_t> &bytes) {
+  size_t read_pos = 0;
+  EXPECT_CALL(uart, available()).WillRepeatedly(Invoke([&bytes, &read_pos]() { return bytes.size() - read_pos; }));
+  EXPECT_CALL(uart, read_array(_, 1)).WillRepeatedly(Invoke([&bytes, &read_pos](uint8_t *data, size_t) {
+    if (read_pos >= bytes.size())
+      return false;
+    *data = bytes[read_pos++];
+    return true;
+  }));
+  interface.loop();
+}
+
+// Test basic frame sending
+TEST_F(UartPacketInterfaceTest, SendSimpleFrame) {
+  std::vector<uint8_t> data = {0x01, 0x02, 0x03};
+  PacketBuffer buffer(data);
+
+  // Set up the mock to accumulate bytes
+  ASSERT_EQ(uart_.written_data.size(), 0);
+  interface_.send_to_interface(buffer, {});
+  // Verify the accumulated bytes
+  ASSERT_EQ(uart_.written_data.size(), 5);
+
+  std::vector<uint8_t> expected = {0x7E, 0x01, 0x02, 0x03, 0x7E};
+  EXPECT_EQ(uart_.written_data, expected);
+}
+// Test byte stuffing for FLAG_BYTE
+TEST_F(UartPacketInterfaceTest, SendWithFlagByteStuffing) {
+  std::vector<uint8_t> data = {0x01, 0x7E, 0x03};
+  PacketBuffer buffer(data);
+
+  uart_.clear();
+  interface_.send_to_interface(buffer, {});
+
+  // Should escape 0x7E as 0x7D 0x5E
+  std::vector<uint8_t> expected = {0x7E, 0x01, 0x7D, 0x5E, 0x03, 0x7E};
+  EXPECT_EQ(uart_.written_data, expected);
+}
+
+// Test byte stuffing for CONTROL_BYTE
+TEST_F(UartPacketInterfaceTest, SendWithControlByteStuffing) {
+  std::vector<uint8_t> data = {0x01, 0x7D, 0x03};
+  PacketBuffer buffer(data);
+
+  uart_.clear();
+  interface_.send_to_interface(buffer, {});
+
+  // Should escape 0x7D as 0x7D 0x5D
+  std::vector<uint8_t> expected = {0x7E, 0x01, 0x7D, 0x5D, 0x03, 0x7E};
+  EXPECT_EQ(uart_.written_data, expected);
+}
+
+// Test sending empty frame
+TEST_F(UartPacketInterfaceTest, SendEmptyFrame) {
+  std::vector<uint8_t> data = {};
+  PacketBuffer buffer(data);
+
+  interface_.send_to_interface(buffer, {});
+
+  // Empty data should return without sending
+  EXPECT_EQ(uart_.written_data.size(), 0);
+}
+
+// Test receiving simple frame
+TEST_F(UartPacketInterfaceTest, ReceiveSimpleFrame) {
+  std::vector<uint8_t> frame_data = {0x7E, 0x01, 0x02, 0x03, 0x7E};
+  size_t read_pos = 0;
+
+  EXPECT_CALL(uart_, available()).WillRepeatedly(Invoke([&frame_data, &read_pos]() {
+    return frame_data.size() - read_pos;
+  }));
+
+  EXPECT_CALL(uart_, read_array(_, 1)).WillRepeatedly(Invoke([&frame_data, &read_pos](uint8_t *data, size_t) {
+    if (read_pos >= frame_data.size())
+      return false;
+    *data = frame_data[read_pos++];
+    return true;
+  }));
+
+  interface_.loop();
+
+  ASSERT_EQ(received_packets_.size(), 1);
+  std::vector<uint8_t> expected = {0x01, 0x02, 0x03};
+  EXPECT_EQ(received_packets_[0], expected);
+}
+
+// Test receiving frame with FLAG_BYTE escape
+TEST_F(UartPacketInterfaceTest, ReceiveFrameWithFlagEscape) {
+  std::vector<uint8_t> frame_data = {0x7E, 0x01, 0x7D, 0x5E, 0x03, 0x7E};
+  size_t read_pos = 0;
+
+  EXPECT_CALL(uart_, available()).WillRepeatedly(Invoke([&frame_data, &read_pos]() {
+    return frame_data.size() - read_pos;
+  }));
+
+  EXPECT_CALL(uart_, read_array(_, 1)).WillRepeatedly(Invoke([&frame_data, &read_pos](uint8_t *data, size_t) {
+    if (read_pos >= frame_data.size())
+      return false;
+    *data = frame_data[read_pos++];
+    return true;
+  }));
+
+  interface_.loop();
+
+  ASSERT_EQ(received_packets_.size(), 1);
+  std::vector<uint8_t> expected = {0x01, 0x7E, 0x03};  // 0x7E unescaped
+  EXPECT_EQ(received_packets_[0], expected);
+}
+
+// Test receiving frame with CONTROL_BYTE escape
+TEST_F(UartPacketInterfaceTest, ReceiveFrameWithControlEscape) {
+  std::vector<uint8_t> frame_data = {0x7E, 0x01, 0x7D, 0x5D, 0x03, 0x7E};
+  size_t read_pos = 0;
+
+  EXPECT_CALL(uart_, available()).WillRepeatedly(Invoke([&frame_data, &read_pos]() {
+    return frame_data.size() - read_pos;
+  }));
+
+  EXPECT_CALL(uart_, read_array(_, 1)).WillRepeatedly(Invoke([&frame_data, &read_pos](uint8_t *data, size_t) {
+    if (read_pos >= frame_data.size())
+      return false;
+    *data = frame_data[read_pos++];
+    return true;
+  }));
+
+  interface_.loop();
+
+  ASSERT_EQ(received_packets_.size(), 1);
+  std::vector<uint8_t> expected = {0x01, 0x7D, 0x03};  // 0x7D unescaped
+  EXPECT_EQ(received_packets_[0], expected);
+}
+
+// Test receiving multiple frames
+TEST_F(UartPacketInterfaceTest, ReceiveMultipleFrames) {
+  std::vector<uint8_t> frame_data = {0x7E, 0x01, 0x02, 0x7E, 0x7E, 0x03, 0x04, 0x7E};
+  size_t read_pos = 0;
+
+  EXPECT_CALL(uart_, available()).WillRepeatedly(Invoke([&frame_data, &read_pos]() {
+    return frame_data.size() - read_pos;
+  }));
+
+  EXPECT_CALL(uart_, read_array(_, 1)).WillRepeatedly(Invoke([&frame_data, &read_pos](uint8_t *data, size_t) {
+    if (read_pos >= frame_data.size())
+      return false;
+    *data = frame_data[read_pos++];
+    return true;
+  }));
+
+  interface_.loop();
+
+  ASSERT_EQ(received_packets_.size(), 2) << "Expected 2 packets, got " << received_packets_.size();
+  std::vector<uint8_t> expected1 = {0x01, 0x02};
+  std::vector<uint8_t> expected2 = {0x03, 0x04};
+  auto pkt0 = received_packets_[0];
+  auto pkt1 = received_packets_[1];
+  EXPECT_EQ(pkt0, expected1) << "Packet 0 size: " << pkt0.size();
+  EXPECT_EQ(pkt1, expected2) << "Packet 1 size: " << pkt1.size();
+}
+
+// Test receiving empty frame (back-to-back flags)
+TEST_F(UartPacketInterfaceTest, ReceiveEmptyFrame) {
+  std::vector<uint8_t> frame_data = {0x7E, 0x7E};
+  size_t read_pos = 0;
+
+  EXPECT_CALL(uart_, available()).WillRepeatedly(Invoke([&frame_data, &read_pos]() {
+    return frame_data.size() - read_pos;
+  }));
+
+  EXPECT_CALL(uart_, read_array(_, 1)).WillRepeatedly(Invoke([&frame_data, &read_pos](uint8_t *data, size_t) {
+    if (read_pos >= frame_data.size())
+      return false;
+    *data = frame_data[read_pos++];
+    return true;
+  }));
+
+  interface_.loop();
+
+  // Empty frames should not be delivered
+  EXPECT_EQ(received_packets_.size(), 0);
+}
+
+// Test data before first flag is ignored
+TEST_F(UartPacketInterfaceTest, IgnoreDataBeforeFirstFlag) {
+  std::vector<uint8_t> frame_data = {0xFF, 0xFF, 0x7E, 0x01, 0x02, 0x7E};
+  size_t read_pos = 0;
+
+  EXPECT_CALL(uart_, available()).WillRepeatedly(Invoke([&frame_data, &read_pos]() {
+    return frame_data.size() - read_pos;
+  }));
+
+  EXPECT_CALL(uart_, read_array(_, 1)).WillRepeatedly(Invoke([&frame_data, &read_pos](uint8_t *data, size_t) {
+    if (read_pos >= frame_data.size())
+      return false;
+    *data = frame_data[read_pos++];
+    return true;
+  }));
+
+  interface_.loop();
+
+  ASSERT_EQ(received_packets_.size(), 1);
+  std::vector<uint8_t> expected = {0x01, 0x02};
+  EXPECT_EQ(received_packets_[0], expected);
+}
+
+// Test oversized packet is discarded
+TEST_F(UartPacketInterfaceTest, OversizedPacketDiscarded) {
+  uint8_t small_buffer[10]{};
+  UartPacketInterface interface(small_buffer);
+  interface.set_uart_parent(&this->uart_);
+  std::vector<std::vector<uint8_t>> received;
+  interface.add_packet_interface_listener(
+      [&received](const PacketBuffer &data, const PacketMetaData &) { received.push_back(to_vector(data)); });
+
+  // Create a packet larger than buffer
+  std::vector<uint8_t> frame_data = {0x7E};
+  for (int i = 0; i < 15; i++) {
+    frame_data.push_back(0xAA);
+  }
+  frame_data.push_back(0x7E);
+
+  feed(this->uart_, interface, frame_data);
+
+  // Oversized packet should be discarded
+  EXPECT_TRUE(received.empty());
+}
+
+// Test round-trip (send and receive)
+TEST_F(UartPacketInterfaceTest, RoundTrip) {
+  std::vector<uint8_t> original = {0x01, 0x7E, 0x7D, 0x03};
+  PacketBuffer send_buffer(original);
+
+  // Send
+  interface_.send_to_interface(send_buffer, {});
+
+  // Prepare to receive - use the written data as frame data
+  std::vector<uint8_t> frame_data = uart_.written_data;
+  size_t read_pos = 0;
+
+  EXPECT_CALL(uart_, available()).WillRepeatedly(Invoke([&frame_data, &read_pos]() {
+    return frame_data.size() - read_pos;
+  }));
+
+  EXPECT_CALL(uart_, read_array(_, 1)).WillRepeatedly(Invoke([&frame_data, &read_pos](uint8_t *data, size_t) {
+    if (read_pos >= frame_data.size())
+      return false;
+    *data = frame_data[read_pos++];
+    return true;
+  }));
+
+  // Receive
+  interface_.loop();
+
+  ASSERT_EQ(received_packets_.size(), 1);
+  EXPECT_EQ(received_packets_[0], original);
+}
+
+// Test all bytes can be transmitted (0x00 to 0xFF)
+TEST_F(UartPacketInterfaceTest, AllByteValues) {
+  std::vector<uint8_t> data;
+  data.reserve(256);
+  for (int i = 0; i != 256; i++) {
+    data.push_back(static_cast<uint8_t>(i));
+  }
+  PacketBuffer send_buffer(data);
+
+  // Send
+  interface_.send_to_interface(send_buffer, {});
+
+  // Prepare to receive - use the written data as frame data
+  std::vector<uint8_t> frame_data = uart_.written_data;
+  size_t read_pos = 0;
+
+  EXPECT_CALL(uart_, available()).WillRepeatedly(Invoke([&frame_data, &read_pos]() {
+    return frame_data.size() - read_pos;
+  }));
+
+  EXPECT_CALL(uart_, read_array(_, 1)).WillRepeatedly(Invoke([&frame_data, &read_pos](uint8_t *data, size_t) {
+    if (read_pos >= frame_data.size())
+      return false;
+    *data = frame_data[read_pos++];
+    return true;
+  }));
+
+  // Receive
+  interface_.loop();
+
+  ASSERT_EQ(received_packets_.size(), 1);
+  EXPECT_EQ(received_packets_[0], data);
+}
+
+// The buffer passed to the constructor is the largest packet, for receiving and sending alike
+TEST_F(UartPacketInterfaceTest, ReceiveLimitedToBuffer) {
+  uint8_t small_buffer[4]{};
+  UartPacketInterface interface(small_buffer);
+  interface.set_uart_parent(&this->uart_);
+  std::vector<std::vector<uint8_t>> received;
+  interface.add_packet_interface_listener(
+      [&received](const PacketBuffer &data, const PacketMetaData &) { received.push_back(to_vector(data)); });
+  // The first packet is longer than the buffer and is dropped; the next one fits
+  feed(this->uart_, interface, {0x7E, 1, 2, 3, 4, 5, 6, 0x7E, 7, 8, 0x7E});
+  EXPECT_EQ(received, (std::vector<std::vector<uint8_t>>{{7, 8}}));
+}
+
+// Test a packet larger than max_packet_size is not sent
+TEST_F(UartPacketInterfaceTest, OversizedPacketNotSent) {
+  uint8_t small_buffer[4]{};
+  UartPacketInterface interface(small_buffer);
+  interface.set_uart_parent(&this->uart_);
+  std::vector<uint8_t> data = {0x01, 0x02, 0x03, 0x04, 0x05};
+  PacketBuffer buffer(data);
+
+  EXPECT_FALSE(interface.send_to_interface(buffer, {}));
+  EXPECT_EQ(uart_.written_data.size(), 0);
+}
+
+// Test a composite buffer longer than one write chunk is framed correctly
+TEST_F(UartPacketInterfaceTest, SendCompositeAcrossChunks) {
+  std::vector<uint8_t> pre(40, 0x7E);
+  std::vector<uint8_t> mid_data = {0x11, 0x22};
+  std::vector<uint8_t> post(30, 0x33);
+  PacketBuffer mid(mid_data);
+  PacketBuffer buffer(pre.data(), pre.size(), &mid, post.data(), post.size());
+
+  ASSERT_TRUE(interface_.send_to_interface(buffer, {}));
+
+  std::vector<uint8_t> expected = {0x7E};
+  for (size_t i = 0; i != pre.size(); i++) {
+    expected.push_back(0x7D);
+    expected.push_back(0x5E);
+  }
+  expected.insert(expected.end(), mid_data.begin(), mid_data.end());
+  expected.insert(expected.end(), post.begin(), post.end());
+  expected.push_back(0x7E);
+  EXPECT_EQ(uart_.written_data, expected);
+}
+
+// Test one flag between frames both ends the first and starts the second
+TEST_F(UartPacketInterfaceTest, SharedFlagBetweenFrames) {
+  feed(uart_, interface_, {0x7E, 0x01, 0x7E, 0x02, 0x03, 0x7E});
+
+  EXPECT_EQ(received_packets_, (std::vector<std::vector<uint8_t>>{{0x01}, {0x02, 0x03}}));
+}
+
+// Test an unfinished frame does not hide the frame after it
+TEST_F(UartPacketInterfaceTest, UnfinishedFrameDoesNotHideNext) {
+  feed(uart_, interface_, {0x7E, 0xAA, 0x7E, 0x01, 0x02, 0x7E});
+
+  EXPECT_EQ(received_packets_, (std::vector<std::vector<uint8_t>>{{0xAA}, {0x01, 0x02}}));
+}
+
+}  // namespace esphome::uart::testing

tests/components/udp/__init__.py

@@ -0,0 +1,6 @@
+from tests.testing_helpers import ComponentManifestOverride
+
+
+def override_manifest(manifest: ComponentManifestOverride) -> None:
+    # benchmark.yaml configures a udp packet_interface, whose to_code waits on the udp component variable.
+    manifest.enable_codegen()

tests/components/udp/benchmark.yaml

@@ -0,0 +1,5 @@
+udp:
+  addresses: ["192.168.1.255"]
+
+packet_interface:
+  - platform: udp

tests/components/udp/udp_packet_interface.cpp

@@ -0,0 +1,78 @@
+#include <gtest/gtest.h>
+
+#include <cstdint>
+#include <vector>
+
+#include "esphome/components/udp/packet_interface/udp_packet_interface.h"
+
+#ifdef USE_NETWORK
+
+namespace esphome::udp::testing {
+
+// Copies a packet into a vector, for comparing in tests
+static std::vector<uint8_t> to_vector(const esphome::packet_interface::PacketBuffer &data) {
+  std::vector<uint8_t> result(data.size());
+  data.copy_to(result.data(), result.size());
+  return result;
+}
+
+using packet_interface::PacketBuffer;
+using packet_interface::PacketMetaData;
+using Packet = std::vector<uint8_t>;
+
+// The copy buffer is a base, so it is set up before the link's constructor sees it
+struct UdpBufferStorage {
+  uint8_t tx_buffer_storage[8]{};
+};
+
+class TestUdp : public UdpBufferStorage, public UdpPacketInterface {
+ public:
+  explicit TestUdp(UDPComponent *udp) : UdpPacketInterface(udp, this->tx_buffer_storage) {
+    this->add_packet_interface_listener(
+        [this](const PacketBuffer &data, const PacketMetaData &) { this->received.push_back(to_vector(data)); });
+  }
+  using UdpPacketInterface::receive_;
+
+  std::vector<Packet> received;
+};
+
+// The udp component is not set up, so it has no destinations and a send does nothing
+class UdpPacketInterfaceTest : public ::testing::Test {
+ protected:
+  UDPComponent udp_;
+  TestUdp link_{&this->udp_};
+};
+
+TEST_F(UdpPacketInterfaceTest, ReceivedPacketsUpToMaxPassedUp) {
+  Packet packet{1, 2, 3, 4, 5, 6, 7, 8};
+  this->link_.receive_(packet);
+  Packet oversized{1, 2, 3, 4, 5, 6, 7, 8, 9};
+  this->link_.receive_(oversized);
+  EXPECT_EQ(this->link_.received, std::vector<Packet>{packet});
+}
+
+TEST_F(UdpPacketInterfaceTest, SendsContiguousAndSplitPackets) {
+  this->link_.setup();
+  Packet packet{1, 2, 3, 4};
+  EXPECT_TRUE(this->link_.send_to_interface(PacketBuffer(packet), {}));
+  uint8_t header = 0;
+  PacketBuffer body(packet);
+  EXPECT_TRUE(this->link_.send_to_interface(PacketBuffer(&header, 1, &body, nullptr, 0), {}));
+  // A packet split across buffers is joined in the copy buffer before it is sent
+  const auto *storage = this->link_.tx_buffer_storage;
+  EXPECT_EQ(Packet(storage, storage + 5), (Packet{0, 1, 2, 3, 4}));
+}
+
+TEST_F(UdpPacketInterfaceTest, OversizedPacketNotSent) {
+  this->link_.setup();
+  Packet packet{1, 2, 3, 4, 5, 6, 7, 8, 9};
+  EXPECT_FALSE(this->link_.send_to_interface(PacketBuffer(packet), {}));
+  uint8_t header = 0;
+  Packet body_data{1, 2, 3, 4, 5, 6, 7, 8};
+  PacketBuffer body(body_data);
+  EXPECT_FALSE(this->link_.send_to_interface(PacketBuffer(&header, 1, &body, nullptr, 0), {}));
+}
+
+}  // namespace esphome::udp::testing
+
+#endif

tests/script/test_build_helpers.py

@@ -74,3 +74,19 @@ def test_populate_dependency_config_populates_defaults() -> None:
         register_platform_fn=lambda domain: None,
     )
     assert config["ok"] == {"default": 1}
+
+
+def test_load_component_yaml_configs_extends_lists(tmp_path: Path) -> None:
+    """Several directories can each add entries to one platform component."""
+    (tmp_path / "first").mkdir()
+    (tmp_path / "first" / "benchmark.yaml").write_text(
+        "uart:\n  port: /dev/a\npacket_interface:\n  - platform: uart\n"
+    )
+    (tmp_path / "second").mkdir()
+    (tmp_path / "second" / "benchmark.yaml").write_text(
+        "uart:\n  port: /dev/b\npacket_interface:\n  - platform: udp\n"
+    )
+    merged = build_helpers.load_component_yaml_configs(["first", "second"], tmp_path)
+    assert merged["packet_interface"] == [{"platform": "uart"}, {"platform": "udp"}]
+    # Other values are taken from the first directory that sets them
+    assert merged["uart"] == {"port": "/dev/a"}

tests/unit_tests/test_packet_interface.py

@@ -0,0 +1,118 @@
+"""Unit tests for the packet_interface component."""
+
+from typing import Any
+
+import pytest
+
+from esphome import config_validation as cv
+from esphome.components import packet_interface
+from esphome.components.packet_interface import CONF_MAX_PACKET_SIZE
+from esphome.components.packet_interface.layers import (
+    CONF_RELIABILITY,
+    RELIABILITY,
+    STACK_ORDER,
+    LayerKind,
+)
+from esphome.components.packet_interface.layers.hdlc_reliability import (
+    CONF_MAX_QUEUE_LENGTH,
+)
+from esphome.components.uart import packet_interface as uart_packet_interface
+from esphome.components.udp import packet_interface as udp_packet_interface
+
+
+@pytest.mark.parametrize(
+    ("schema", "default", "limit"),
+    [
+        (uart_packet_interface.CONFIG_SCHEMA, 508, 4096),
+        (udp_packet_interface.CONFIG_SCHEMA, 508, 508),
+    ],
+)
+def test_platform_max_packet_size(
+    setup_core, schema: cv.Schema, default: int, limit: int
+) -> None:
+    """Each platform has its own default and upper limit for max_packet_size."""
+    assert schema({})[CONF_MAX_PACKET_SIZE] == default
+    assert schema({CONF_MAX_PACKET_SIZE: limit})[CONF_MAX_PACKET_SIZE] == limit
+    with pytest.raises(cv.Invalid):
+        schema({CONF_MAX_PACKET_SIZE: limit + 1})
+    with pytest.raises(cv.Invalid):
+        schema({CONF_MAX_PACKET_SIZE: 15})
+
+
+def test_schema_default(setup_core) -> None:
+    """packet_interface_schema applies the default it is given."""
+    schema = packet_interface.packet_interface_schema(
+        packet_interface.PacketInterface, 100
+    )
+    assert schema({})[CONF_MAX_PACKET_SIZE] == 100
+
+
+def test_reliability_defaults(setup_core) -> None:
+    """An empty reliability key selects the HDLC layer with its defaults."""
+    config = uart_packet_interface.CONFIG_SCHEMA({CONF_RELIABILITY: None})
+    reliability = config[CONF_RELIABILITY]
+    assert reliability["type"] == "hdlc"
+    assert reliability["timeout"].total_milliseconds == 200
+    assert reliability[CONF_MAX_QUEUE_LENGTH] == 4
+    assert reliability["max_retries"] == 5
+
+
+def test_reliability_queue_length_limit(setup_core) -> None:
+    """The queue cannot hold more frames than 3 bit sequence numbers allow."""
+    with pytest.raises(cv.Invalid):
+        uart_packet_interface.CONFIG_SCHEMA(
+            {CONF_RELIABILITY: {CONF_MAX_QUEUE_LENGTH: 8}}
+        )
+
+
+def test_reliability_timeout_minimum(setup_core) -> None:
+    """A timeout shorter than a few loop passes cannot work."""
+    uart_packet_interface.CONFIG_SCHEMA({CONF_RELIABILITY: {"timeout": "50ms"}})
+    with pytest.raises(cv.Invalid):
+        uart_packet_interface.CONFIG_SCHEMA({CONF_RELIABILITY: {"timeout": "40ms"}})
+
+
+def test_ack_delay_shorter_than_timeout(setup_core) -> None:
+    """The acknowledgement must not wait longer than the peer's timeout."""
+    reliability = uart_packet_interface.CONFIG_SCHEMA(
+        {CONF_RELIABILITY: {"timeout": "500ms", "ack_delay": "100ms"}}
+    )[CONF_RELIABILITY]
+    assert reliability["ack_delay"].total_milliseconds == 100
+    with pytest.raises(cv.Invalid, match="shorter"):
+        uart_packet_interface.CONFIG_SCHEMA(
+            {CONF_RELIABILITY: {"timeout": "500ms", "ack_delay": "500ms"}}
+        )
+
+
+def test_layer_types_registered() -> None:
+    """Importing packet_interface registers the built-in layer types."""
+    assert {kind.key: set(kind.types) for kind in STACK_ORDER} == {
+        CONF_RELIABILITY: {"hdlc"},
+    }
+
+
+async def _build(config: dict, lower: Any) -> Any:
+    return lower
+
+
+def test_registered_type_selectable(setup_core) -> None:
+    """A newly registered layer type can be selected with type."""
+    kind = LayerKind("test_kind", "test")
+    kind.register("test", schema=cv.Schema({}))(_build)
+    config = kind.schema()({"type": "test"})
+    assert config["type"] == "test"
+    assert kind.get_type(config).build is _build
+
+
+def test_duplicate_layer_type_rejected(setup_core) -> None:
+    """Registering a type under a name already in use is an error, not a silent replacement."""
+    kind = LayerKind("test_kind", "test")
+    kind.register("test", schema=cv.Schema({}))(_build)
+    with pytest.raises(ValueError, match="already registered"):
+        kind.register("test", schema=cv.Schema({}))(_build)
+
+
+def test_late_registration_rejected(setup_core) -> None:
+    """A type registered after the schemas were built would be missing from them, so it is an error."""
+    with pytest.raises(ValueError, match="after the schemas were built"):
+        RELIABILITY.register("late", schema=cv.Schema({}))(_build)