Merge branch 'api-single-decode-virtual' into api-null-string-defaults

Co-authored-by: J. Nick Koston <nick@home-assistant.io>

.github/workflows/stale.yml

@@ -33,7 +33,7 @@ jobs:
         and will be closed if no further activity occurs within 7 days.
 
         If you are the author of this PR, please leave a comment if you want
-        to keep it open. Also, please rebase your PR onto the latest dev
+        to keep it open. Also, please merge the latest dev branch into your
         branch to ensure that it's up to date with the latest changes.
 
         Thank you for your contribution!

docker/Dockerfile

@@ -22,7 +22,7 @@ RUN \
     -r /requirements.txt
 
 # Install the ESPHome Device Builder dashboard.
-RUN uv pip install --no-cache-dir esphome-device-builder==1.14.5
+RUN uv pip install --no-cache-dir esphome-device-builder==1.14.6
 
 RUN \
     platformio settings set enable_telemetry No \

esphome/components/api/api.proto

@@ -77,6 +77,7 @@ service APIConnection {
   rpc serial_proxy_set_modem_pins(SerialProxySetModemPinsRequest) returns (void) {}
   rpc serial_proxy_get_modem_pins(SerialProxyGetModemPinsRequest) returns (void) {}
   rpc serial_proxy_request(SerialProxyRequest) returns (void) {}
+  rpc serial_proxy_set_mode(SerialProxySetModeRequest) returns (void) {}
 }
 
 
@@ -2726,7 +2727,8 @@ enum SerialProxyParity {
   SERIAL_PROXY_PARITY_ODD = 2;
 }
 
-// Configure UART parameters for a serial proxy instance
+// Configure UART parameters for a serial proxy instance. Only the subscribed client may
+// configure the port; others are refused with PORT_IN_USE (since API 1.17).
 message SerialProxyConfigureRequest {
   option (id) = 138;
   option (source) = SOURCE_CLIENT;
@@ -2752,7 +2754,8 @@ message SerialProxyDataReceived {
   bytes data = 2;               // Raw data received from the serial device
 }
 
-// Write data to a serial device
+// Write data to a serial device. Only the subscribed client may write; writes from
+// others are ignored (since API 1.17).
 message SerialProxyWriteRequest {
   option (id) = 140;
   option (source) = SOURCE_CLIENT;
@@ -2763,7 +2766,8 @@ message SerialProxyWriteRequest {
   bytes data = 2;               // Raw data to write to the serial device
 }
 
-// Set modem control pin states (RTS and DTR)
+// Set modem control pin states (RTS and DTR). Only the subscribed client may set them;
+// others are refused with PORT_IN_USE (since API 1.17).
 message SerialProxySetModemPinsRequest {
   option (id) = 141;
   option (source) = SOURCE_CLIENT;
@@ -2802,6 +2806,7 @@ enum SerialProxyRequestType {
   // error the device answers with INVALID_ARGUMENT.
   SERIAL_PROXY_REQUEST_TYPE_CONFIGURE = 3;      // Acknowledges a SerialProxyConfigureRequest
   SERIAL_PROXY_REQUEST_TYPE_SET_MODEM_PINS = 4; // Acknowledges a SerialProxySetModemPinsRequest
+  SERIAL_PROXY_REQUEST_TYPE_SET_MODE = 5;       // Acknowledges a SerialProxySetModeRequest (since API 1.17)
 }
 
 enum SerialProxyStatus {
@@ -2814,7 +2819,8 @@ enum SerialProxyStatus {
   SERIAL_PROXY_STATUS_INVALID_ARGUMENT = 6; // Invalid instance index or parameter value
 }
 
-// Generic request message for simple serial proxy operations
+// Generic request message for simple serial proxy operations. FLUSH requires an active
+// subscription; it is refused with PORT_IN_USE otherwise (since API 1.17).
 message SerialProxyRequest {
   option (id) = 144;
   option (source) = SOURCE_CLIENT;
@@ -2838,6 +2844,29 @@ message SerialProxyRequestResponse {
   string error_message = 4;            // Additional detail on failure (optional)
 }
 
+// How a port treats the bytes passing through it. RAW is a plain byte pipe; PROTOCOL
+// activates the port's protocol-aware tap (if one is configured), letting it observe
+// traffic and inject protocol bytes such as acknowledgements. Which protocol the tap
+// speaks is a property of the device configuration, discoverable from the tap
+// component's own API surface. A client that is about to flash firmware selects RAW
+// first, which definitively disables that injection.
+enum SerialProxyMode {
+  SERIAL_PROXY_MODE_RAW = 0;
+  SERIAL_PROXY_MODE_PROTOCOL = 1;
+}
+
+// Only the subscribed client may change the mode; any other caller -- including one that
+// never subscribed -- is refused with PORT_IN_USE. PROTOCOL is refused with NOT_SUPPORTED
+// when the port has no protocol-aware tap configured.
+message SerialProxySetModeRequest {
+  option (id) = 152;
+  option (source) = SOURCE_CLIENT;
+  option (ifdef) = "USE_SERIAL_PROXY";
+
+  uint32 instance = 1;
+  SerialProxyMode mode = 2;
+}
+
 // ==================== BLUETOOTH CONNECTION PARAMS ====================
 message BluetoothSetConnectionParamsRequest {
   option (id) = 145;

esphome/components/api/api_connection.cpp

@@ -1661,6 +1661,7 @@ void APIConnection::on_serial_proxy_request(const SerialProxyRequest &msg) {
       break;
     case enums::SERIAL_PROXY_REQUEST_TYPE_CONFIGURE:
     case enums::SERIAL_PROXY_REQUEST_TYPE_SET_MODEM_PINS:
+    case enums::SERIAL_PROXY_REQUEST_TYPE_SET_MODE:
       // Response-only discriminators; never valid in a request
       ESP_LOGW(TAG, "Response-only serial proxy request type: %" PRIu32, static_cast<uint32_t>(msg.type));
       status = enums::SERIAL_PROXY_STATUS_INVALID_ARGUMENT;
@@ -1673,6 +1674,19 @@ void APIConnection::on_serial_proxy_request(const SerialProxyRequest &msg) {
   send_serial_proxy_ack(this, msg.instance, msg.type, status);
 }
 
+void APIConnection::on_serial_proxy_set_mode_request(const SerialProxySetModeRequest &msg) {
+  auto &proxies = App.get_serial_proxies();
+  if (msg.instance >= proxies.size()) {
+    ESP_LOGW(TAG, "Serial proxy instance %" PRIu32 " out of range", msg.instance);
+    send_serial_proxy_ack(this, msg.instance, enums::SERIAL_PROXY_REQUEST_TYPE_SET_MODE,
+                          enums::SERIAL_PROXY_STATUS_INVALID_ARGUMENT);
+    return;
+  }
+  serial_proxy::SerialProxyResult result = proxies[msg.instance]->set_mode_from_client(this, msg.mode);
+  send_serial_proxy_ack(this, msg.instance, enums::SERIAL_PROXY_REQUEST_TYPE_SET_MODE,
+                        serial_proxy_result_to_status(result));
+}
+
 void APIConnection::send_serial_proxy_data(const SerialProxyDataReceived &msg) {
   if (!this->send_message(msg)) {
     ESP_LOGV(TAG, "Serial proxy data dropped, TCP buffer full");
@@ -1799,7 +1813,7 @@ bool APIConnection::send_hello_response_(const HelloRequest &msg) {
 
   HelloResponse resp;
   resp.api_version_major = 1;
-  resp.api_version_minor = 16;
+  resp.api_version_minor = 17;
   // Send only the version string - the client only logs this for debugging and doesn't use it otherwise
   resp.server_info = ESPHOME_VERSION_REF;
   resp.name = StringRef(App.get_name());
@@ -2255,7 +2269,12 @@ bool APIConnection::send_message_(uint32_t payload_size, uint16_t message_type,
   // Capacity reserved above, cannot fail
   (void) shared_buf.resize(write_start + payload_size);
   ProtoWriteBuffer buffer{&shared_buf, write_start};
-  encode_fn(msg, buffer PROTO_ENCODE_DEBUG_INIT(&shared_buf));
+  uint8_t *end = encode_fn(msg, buffer PROTO_ENCODE_DEBUG_INIT(&shared_buf));
+#ifdef ESPHOME_DEBUG_API
+  assert(end == shared_buf.data() + shared_buf.size());
+#else
+  (void) end;
+#endif
   return this->send_buffer(ProtoWriteBuffer{&shared_buf}, message_type);
 }
 // encode_to_buffer is defined inline in api_connection.h (ESPHOME_ALWAYS_INLINE)

esphome/components/api/api_connection.h

@@ -244,6 +244,7 @@ class APIConnection final : public APIServerConnectionBase {
   void on_serial_proxy_set_modem_pins_request(const SerialProxySetModemPinsRequest &msg);
   void on_serial_proxy_get_modem_pins_request(const SerialProxyGetModemPinsRequest &msg);
   void on_serial_proxy_request(const SerialProxyRequest &msg);
+  void on_serial_proxy_set_mode_request(const SerialProxySetModeRequest &msg);
   void send_serial_proxy_data(const SerialProxyDataReceived &msg);
 #endif
 
@@ -345,11 +346,7 @@ class APIConnection final : public APIServerConnectionBase {
   /// Returns false as soon as the TCP buffer is full. Marked nodiscard so we
   /// have no silent failures: every caller must handle (or log) a refusal.
   template<typename T> [[nodiscard]] bool send_message(const T &msg) {
-    if constexpr (T::ESTIMATED_SIZE == 0) {
-      return this->send_message_(0, T::MESSAGE_TYPE, &encode_msg_noop, &msg);
-    } else {
-      return this->send_message_(msg.calculate_size(), T::MESSAGE_TYPE, &proto_encode_msg<T>, &msg);
-    }
+    return this->send_message_(T::calc_size_msg(&msg), T::MESSAGE_TYPE, &T::encode_msg, &msg);
   }
 
   /// Clear the shared write buffer and reserve space for the first message.
@@ -405,16 +402,6 @@ class APIConnection final : public APIServerConnectionBase {
   void process_state_subscriptions_();
 #endif
 
-  // Size thunk — converts void* back to concrete type for direct calculate_size() call
-  template<typename T> static uint32_t calc_size(const void *msg) {
-    return static_cast<const T *>(msg)->calculate_size();
-  }
-
-  // Shared no-op encode thunk for empty messages (ESTIMATED_SIZE == 0)
-  static uint8_t *encode_msg_noop(const void *, ProtoWriteBuffer &buf PROTO_ENCODE_DEBUG_PARAM) {
-    return buf.get_pos();
-  }
-
   // Non-template buffer management for send_message
   bool send_message_(uint32_t payload_size, uint16_t message_type, MessageEncodeFn encode_fn, const void *msg);
 
@@ -433,11 +420,7 @@ class APIConnection final : public APIServerConnectionBase {
   // Hot paths (state/info) go through fill_and_encode_entity_state/info instead.
   // batch_message_type_ is already set by dispatch_message_ before reaching here.
   template<typename T> static uint16_t encode_message_to_buffer(T &msg, APIConnection *conn, uint32_t remaining_size) {
-    if constexpr (T::ESTIMATED_SIZE == 0) {
-      return encode_to_buffer_slow(0, &encode_msg_noop, &msg, conn, remaining_size);
-    } else {
-      return encode_to_buffer_slow(msg.calculate_size(), &proto_encode_msg<T>, &msg, conn, remaining_size);
-    }
+    return encode_to_buffer_slow(T::calc_size_msg(&msg), &T::encode_msg, &msg, conn, remaining_size);
   }
 
   // Non-template core — fills state fields and encodes
@@ -449,7 +432,7 @@ class APIConnection final : public APIServerConnectionBase {
   template<typename T>
   static uint16_t fill_and_encode_entity_state(EntityBase *entity, T &msg, APIConnection *conn,
                                                uint32_t remaining_size) {
-    return fill_and_encode_entity_state(entity, msg, &calc_size<T>, &proto_encode_msg<T>, conn, remaining_size);
+    return fill_and_encode_entity_state(entity, msg, &T::calc_size_msg, &T::encode_msg, conn, remaining_size);
   }
 
   // Non-template core — fills info fields, allocates buffers, and encodes
@@ -461,7 +444,7 @@ class APIConnection final : public APIServerConnectionBase {
   template<typename T>
   static uint16_t fill_and_encode_entity_info(EntityBase *entity, T &msg, APIConnection *conn,
                                               uint32_t remaining_size) {
-    return fill_and_encode_entity_info(entity, msg, &calc_size<T>, &proto_encode_msg<T>, conn, remaining_size);
+    return fill_and_encode_entity_info(entity, msg, &T::calc_size_msg, &T::encode_msg, conn, remaining_size);
   }
 
   // Non-template core — fills device_class, then delegates to fill_and_encode_entity_info
@@ -475,8 +458,8 @@ class APIConnection final : public APIServerConnectionBase {
   static uint16_t fill_and_encode_entity_info_with_device_class(EntityBase *entity, T &msg,
                                                                 StringRef &device_class_field, APIConnection *conn,
                                                                 uint32_t remaining_size) {
-    return fill_and_encode_entity_info_with_device_class(entity, msg, device_class_field, &calc_size<T>,
-                                                         &proto_encode_msg<T>, conn, remaining_size);
+    return fill_and_encode_entity_info_with_device_class(entity, msg, device_class_field, &T::calc_size_msg,
+                                                         &T::encode_msg, conn, remaining_size);
   }
 
 #ifdef USE_VOICE_ASSISTANT

esphome/components/api/api_connection_buffer.h

@@ -46,7 +46,13 @@ inline uint16_t ESPHOME_ALWAYS_INLINE APIConnection::encode_to_buffer(uint32_t c
     return 0;
   }
   ProtoWriteBuffer buffer{&shared_buf, shared_buf.size() - calculated_size};
-  encode_fn(msg, buffer PROTO_ENCODE_DEBUG_INIT(&shared_buf));
+  uint8_t *end = encode_fn(msg, buffer PROTO_ENCODE_DEBUG_INIT(&shared_buf));
+#ifdef ESPHOME_DEBUG_API
+  // A body that writes fewer bytes than calculate_size() promised would ship stale buffer bytes
+  assert(end == shared_buf.data() + shared_buf.size());
+#else
+  (void) end;
+#endif
 
   return total_calculated_size;
 }

esphome/components/api/api_pb2_dump.cpp

@@ -854,6 +854,8 @@ template<> const char *proto_enum_to_string<enums::SerialProxyRequestType>(enums
       return ESPHOME_PSTR("SERIAL_PROXY_REQUEST_TYPE_CONFIGURE");
     case enums::SERIAL_PROXY_REQUEST_TYPE_SET_MODEM_PINS:
       return ESPHOME_PSTR("SERIAL_PROXY_REQUEST_TYPE_SET_MODEM_PINS");
+    case enums::SERIAL_PROXY_REQUEST_TYPE_SET_MODE:
+      return ESPHOME_PSTR("SERIAL_PROXY_REQUEST_TYPE_SET_MODE");
     default:
       return ESPHOME_PSTR("UNKNOWN");
   }
@@ -878,6 +880,16 @@ template<> const char *proto_enum_to_string<enums::SerialProxyStatus>(enums::Ser
       return ESPHOME_PSTR("UNKNOWN");
   }
 }
+template<> const char *proto_enum_to_string<enums::SerialProxyMode>(enums::SerialProxyMode value) {
+  switch (value) {
+    case enums::SERIAL_PROXY_MODE_RAW:
+      return ESPHOME_PSTR("SERIAL_PROXY_MODE_RAW");
+    case enums::SERIAL_PROXY_MODE_PROTOCOL:
+      return ESPHOME_PSTR("SERIAL_PROXY_MODE_PROTOCOL");
+    default:
+      return ESPHOME_PSTR("UNKNOWN");
+  }
+}
 #endif
 
 const char *HelloRequest::dump_to(DumpBuffer &out) const {
@@ -2805,6 +2817,12 @@ const char *SerialProxyRequestResponse::dump_to(DumpBuffer &out) const {
   dump_field(out, ESPHOME_PSTR("error_message"), this->error_message);
   return out.c_str();
 }
+const char *SerialProxySetModeRequest::dump_to(DumpBuffer &out) const {
+  MessageDumpHelper helper(out, ESPHOME_PSTR("SerialProxySetModeRequest"));
+  dump_field(out, ESPHOME_PSTR("instance"), this->instance);
+  dump_field(out, ESPHOME_PSTR("mode"), static_cast<enums::SerialProxyMode>(this->mode));
+  return out.c_str();
+}
 #endif
 #ifdef USE_BLUETOOTH_PROXY_CONNECTIONS
 const char *BluetoothSetConnectionParamsRequest::dump_to(DumpBuffer &out) const {

esphome/components/api/api_pb2_service.cpp

@@ -712,6 +712,17 @@ void APIConnection::read_message_(uint32_t msg_size, uint32_t msg_type, const ui
       this->on_device_capabilities_request();
       break;
     }
+#ifdef USE_SERIAL_PROXY
+    case SerialProxySetModeRequest::MESSAGE_TYPE: {
+      SerialProxySetModeRequest msg;
+      msg.decode(msg_data, msg_size);
+#ifdef HAS_PROTO_MESSAGE_DUMP
+      this->log_receive_message_(LOG_STR("on_serial_proxy_set_mode_request"), msg);
+#endif
+      this->on_serial_proxy_set_mode_request(msg);
+      break;
+    }
+#endif
     default:
       break;
   }

esphome/components/api/api_pb2_service.h

@@ -235,6 +235,9 @@ class APIServerConnectionBase {
   void on_serial_proxy_request(const SerialProxyRequest &value){};
 #endif
 
+#ifdef USE_SERIAL_PROXY
+  void on_serial_proxy_set_mode_request(const SerialProxySetModeRequest &value){};
+#endif
 #ifdef USE_BLUETOOTH_PROXY_CONNECTIONS
   void on_bluetooth_set_connection_params_request(const BluetoothSetConnectionParamsRequest &value){};
 #endif

esphome/components/api/api_server.cpp

@@ -433,8 +433,9 @@ void APIServer::send_homeassistant_action(const HomeassistantActionRequest &call
     // Home Assistant subscribes to actions shortly *after* authenticating, so actions
     // fired right at connection time (on_client_connected, on_time_sync, ...) can
     // arrive before the subscription and are lost - warn instead of failing silently.
-    ESP_LOGW(TAG, "Home Assistant %s '%s' dropped; %s",
-             call.is_event ? LOG_STR_LITERAL("event") : LOG_STR_LITERAL("action"), call.service.c_str(),
+    ESP_LOGW(TAG, "Home Assistant %s '%.*s' dropped; %s",
+             call.is_event ? LOG_STR_LITERAL("event") : LOG_STR_LITERAL("action"),
+             static_cast<int>(call.service.size()), call.service.empty() ? "" : call.service.c_str(),
              this->is_connected() ? LOG_STR_LITERAL("client has not subscribed to actions (yet)")
                                   : LOG_STR_LITERAL("no client connected"));
   }

esphome/components/api/proto.cpp

@@ -214,73 +214,74 @@ void ProtoDecodableMessage::decode(const uint8_t *buffer, size_t length) {
   const uint8_t *ptr = buffer;
   const uint8_t *end = buffer + length;
 
-  while (ptr < end) {
-    // Parse field header - ptr < end guarantees len >= 1
+  // Single-byte varints dominate, so that case advances the cursor inline.
+  auto read_varint = [&](proto_varint_value_t &value) ESPHOME_ALWAYS_INLINE {
+    if (ptr == end)
+      return false;
+    if (*ptr < 0x80) [[likely]] {
+      value = *ptr++;
+      return true;
+    }
     auto res = ProtoVarInt::parse_non_empty(ptr, end - ptr);
-    if (!res.has_value()) {
+    if (!res.has_value())
+      return false;
+    value = res.value;
+    ptr += res.consumed;
+    return true;
+  };
+
+  while (ptr < end) {
+    proto_varint_value_t tag_value;
+    if (!read_varint(tag_value)) {
       ESP_LOGV(TAG, "Invalid field start at offset %ld", (long) (ptr - buffer));
       return;
     }
 
-    uint32_t tag = static_cast<uint32_t>(res.value);
+    uint32_t tag = static_cast<uint32_t>(tag_value);
     uint32_t field_type = tag & WIRE_TYPE_MASK;
-    uint32_t field_id = tag >> 3;
-    ptr += res.consumed;
+    // Length-delimited fields move this past the length prefix
+    const uint8_t *data = ptr;
+    proto_varint_value_t scalar;
 
-    switch (field_type) {
-      case WIRE_TYPE_VARINT: {  // VarInt
-        res = ProtoVarInt::parse(ptr, end - ptr);
-        if (!res.has_value()) {
-          ESP_LOGV(TAG, "Invalid VarInt at offset %ld", (long) (ptr - buffer));
-          return;
-        }
-        if (!this->decode_varint(field_id, res.value)) {
-          ESP_LOGV(TAG, "Cannot decode VarInt field %" PRIu32 " with value %" PRIu64 "!", field_id,
-                   static_cast<uint64_t>(res.value));
-        }
-        ptr += res.consumed;
-        break;
-      }
-      case WIRE_TYPE_LENGTH_DELIMITED: {  // Length-delimited
-        res = ProtoVarInt::parse(ptr, end - ptr);
-        if (!res.has_value()) {
-          ESP_LOGV(TAG, "Invalid Length Delimited at offset %ld", (long) (ptr - buffer));
-          return;
-        }
-        uint32_t field_length = static_cast<uint32_t>(res.value);
-        ptr += res.consumed;
-        if (field_length > static_cast<size_t>(end - ptr)) {
-          ESP_LOGV(TAG, "Out-of-bounds Length Delimited at offset %ld", (long) (ptr - buffer));
-          return;
-        }
-        if (!this->decode_length(field_id, ProtoLengthDelimited(ptr, field_length))) {
-          ESP_LOGV(TAG, "Cannot decode Length Delimited field %" PRIu32 "!", field_id);
-        }
-        ptr += field_length;
-        break;
-      }
-      case WIRE_TYPE_FIXED32: {  // 32-bit
-        if (end - ptr < 4) {
-          ESP_LOGV(TAG, "Out-of-bounds Fixed32-bit at offset %ld", (long) (ptr - buffer));
-          return;
-        }
-        uint32_t val;
-#if __BYTE_ORDER__ == __ORDER_LITTLE_ENDIAN__
-        // Protobuf fixed32 is little-endian — direct load on LE platforms
-        memcpy(&val, ptr, 4);
-#else
-        val = encode_uint32(ptr[3], ptr[2], ptr[1], ptr[0]);
-#endif
-        if (!this->decode_32bit(field_id, Proto32Bit(val))) {
-          ESP_LOGV(TAG, "Cannot decode 32-bit field %" PRIu32 " with value %" PRIu32 "!", field_id, val);
-        }
-        ptr += 4;
-        break;
-      }
-      default:
-        ESP_LOGV(TAG, "Invalid field type %" PRIu32 " at offset %ld", field_type, (long) (ptr - buffer));
+    if (field_type == WIRE_TYPE_VARINT) [[likely]] {
+      if (!read_varint(scalar)) {
+        ESP_LOGV(TAG, "Invalid VarInt at offset %ld", (long) (ptr - buffer));
         return;
+      }
+    } else {
+      switch (field_type) {
+        case WIRE_TYPE_LENGTH_DELIMITED: {
+          proto_varint_value_t length_value;
+          if (!read_varint(length_value)) {
+            ESP_LOGV(TAG, "Invalid Length Delimited at offset %ld", (long) (ptr - buffer));
+            return;
+          }
+          uint32_t field_length = static_cast<uint32_t>(length_value);
+          if (field_length > static_cast<size_t>(end - ptr)) {
+            ESP_LOGV(TAG, "Out-of-bounds Length Delimited at offset %ld", (long) (ptr - buffer));
+            return;
+          }
+          data = ptr;
+          scalar = field_length;
+          ptr += field_length;
+          break;
+        }
+        case WIRE_TYPE_FIXED32: {
+          if (end - ptr < 4) {
+            ESP_LOGV(TAG, "Out-of-bounds Fixed32-bit at offset %ld", (long) (ptr - buffer));
+            return;
+          }
+          // Byte loads instead of memcpy: ESP-IDF passes -fno-builtin-memcpy, which made this a call
+          scalar = encode_uint32(ptr[3], ptr[2], ptr[1], ptr[0]);
+          ptr += 4;
+          break;
+        }
+        default:
+          ESP_LOGV(TAG, "Invalid field type %" PRIu32 " at offset %ld", field_type, (long) (ptr - buffer));
+          return;
+      }
     }
+    this->decode_field(tag, data, scalar);
   }
 }
 

esphome/components/api/proto.h

@@ -170,40 +170,43 @@ class ProtoVarInt {
 class ProtoMessage;
 class ProtoSize;
 
-class ProtoLengthDelimited {
+/// Case label for decode_field(): the wire tag of a field, so a field that arrives with another wire
+/// type matches no case.
+constexpr uint32_t proto_tag(uint32_t field_id, uint32_t wire_type) { return (field_id << 3) | wire_type; }
+
+/// One decoded field: the payload pointer and a scalar holding the varint or fixed32 value, or the
+/// length of a length-delimited field. The wire type in the tag says which applies; accessors do not check.
+class ProtoFieldValue {
  public:
-  explicit ProtoLengthDelimited(const uint8_t *value, size_t length) : value_(value), length_(length) {}
-  std::string as_string() const { return std::string(reinterpret_cast<const char *>(this->value_), this->length_); }
+  ProtoFieldValue(const uint8_t *data, proto_varint_value_t scalar) : data_(data), scalar_(scalar) {}
 
-  // Direct access to raw data without string allocation
-  const uint8_t *data() const { return this->value_; }
-  size_t size() const { return this->length_; }
+  proto_varint_value_t as_varint() const { return this->scalar_; }
+  // A bool is sent as 0 or 1, so the low word is enough and saves a second compare with 64 bit varints
+  bool as_bool() const { return static_cast<uint32_t>(this->scalar_) != 0; }
 
-  /// Decode the length-delimited data into a message instance.
+  // Length-delimited accessors
+  const uint8_t *data() const { return this->data_; }
+  size_t size() const { return static_cast<size_t>(this->scalar_); }
+  std::string as_string() const { return std::string(reinterpret_cast<const char *>(this->data_), this->size()); }
+  /// Decode the length-delimited payload into a message instance.
   /// Template preserves concrete type so decode() resolves statically.
-  template<typename T> void decode_to_message(T &msg) const;
+  template<typename T> void decode_to_message(T &msg) const { msg.decode(this->data_, this->size()); }
 
- protected:
-  const uint8_t *const value_;
-  const size_t length_;
-};
-
-class Proto32Bit {
- public:
-  explicit Proto32Bit(uint32_t value) : value_(value) {}
-  uint32_t as_fixed32() const { return this->value_; }
-  int32_t as_sfixed32() const { return static_cast<int32_t>(this->value_); }
+  // Fixed32 accessors
+  uint32_t as_fixed32() const { return static_cast<uint32_t>(this->scalar_); }
+  int32_t as_sfixed32() const { return static_cast<int32_t>(this->as_fixed32()); }
   float as_float() const {
     union {
       uint32_t raw;
       float value;
     } s{};
-    s.raw = this->value_;
+    s.raw = this->as_fixed32();
     return s.value;
   }
 
- protected:
-  const uint32_t value_;
+ private:
+  const uint8_t *data_;
+  proto_varint_value_t scalar_;
 };
 
 // NOTE: Proto64Bit class removed - wire type 1 (64-bit fixed) not supported
@@ -252,7 +255,7 @@ class ProtoWriteBuffer {
    *
    * Following https://protobuf.dev/programming-guides/encoding/#structure
    */
-  void encode_field_raw(uint32_t field_id, uint32_t type) { this->encode_varint_raw((field_id << 3) | type); }
+  void encode_field_raw(uint32_t field_id, uint32_t type) { this->encode_varint_raw(proto_tag(field_id, type)); }
   /// Single-pass encode for repeated submessage elements.
   /// Thin template wrapper; all buffer work is in the non-template core.
   template<typename T> void encode_sub_message(uint32_t field_id, const T &value);
@@ -287,19 +290,31 @@ class ProtoWriteBuffer {
   uint8_t *pos_;
 };
 
+// A four byte unaligned store is a memcpy call on ESP-IDF (-fno-builtin-memcpy) and on ARM cores without
+// unaligned access (Cortex-M0+, ARM9), so those targets share one outlined byte store helper per fixed32
+// field. Elsewhere the write inlines to a single store, or on ESP8266 to a few stores that measured
+// faster than a call, so it stays inline.
+#if defined(USE_ESP32) || (defined(__arm__) && !defined(__ARM_FEATURE_UNALIGNED))
+#define PROTO_OUTLINE_FOR_SIZE __attribute__((noinline))
+#define PROTO_FIXED32_BYTE_STORES true
+#else
+#define PROTO_OUTLINE_FOR_SIZE inline
+#define PROTO_FIXED32_BYTE_STORES false
+#endif
+
 // Varint encoding thresholds — used by both proto_encode_* free functions and ProtoSize.
 constexpr uint32_t VARINT_MAX_1_BYTE = 1 << 7;   // 128
 constexpr uint32_t VARINT_MAX_2_BYTE = 1 << 14;  // 16384
 
-/// Static encode helpers for generated encode() functions.
-/// Generated code hoists buffer.pos_ into a local uint8_t *__restrict__ pos,
-/// then calls these methods which take pos by reference. No struct, no overhead.
-/// For sub-messages, pos is synced back to buffer before the call and reloaded after.
+/// Static encode helpers for the generated encode bodies. Each takes the write cursor by value and
+/// returns it advanced, so outlined calls at -Os chain through the return register instead of a
+/// stack slot. Helpers without a _force suffix skip fields holding the proto3 default.
 class ProtoEncode {
  public:
   /// Write a multi-byte varint directly through a pos pointer.
   template<typename T>
-  static inline void encode_varint_raw_loop(uint8_t *__restrict__ &pos PROTO_ENCODE_DEBUG_PARAM, T value) {
+  [[nodiscard]] static inline uint8_t *encode_varint_raw_loop(uint8_t *__restrict__ pos PROTO_ENCODE_DEBUG_PARAM,
+                                                              T value) {
     do {
       PROTO_ENCODE_CHECK_BOUNDS(pos, 1);
       *pos++ = static_cast<uint8_t>(value | 0x80);
@@ -307,48 +322,49 @@ class ProtoEncode {
     } while (value > 0x7F);
     PROTO_ENCODE_CHECK_BOUNDS(pos, 1);
     *pos++ = static_cast<uint8_t>(value);
+    return pos;
   }
-  static inline void ESPHOME_ALWAYS_INLINE encode_varint_raw(uint8_t *__restrict__ &pos PROTO_ENCODE_DEBUG_PARAM,
-                                                             uint32_t value) {
+  [[nodiscard]] static inline uint8_t *ESPHOME_ALWAYS_INLINE
+  encode_varint_raw(uint8_t *__restrict__ pos PROTO_ENCODE_DEBUG_PARAM, uint32_t value) {
     if (value < VARINT_MAX_1_BYTE) [[likely]] {
       PROTO_ENCODE_CHECK_BOUNDS(pos, 1);
       *pos++ = static_cast<uint8_t>(value);
-      return;
+      return pos;
     }
-    encode_varint_raw_loop(pos PROTO_ENCODE_DEBUG_ARG, value);
+    return encode_varint_raw_loop(pos PROTO_ENCODE_DEBUG_ARG, value);
   }
   /// Encode a varint that is expected to be 1-2 bytes (e.g. zigzag RSSI, small lengths).
-  static inline void ESPHOME_ALWAYS_INLINE encode_varint_raw_short(uint8_t *__restrict__ &pos PROTO_ENCODE_DEBUG_PARAM,
-                                                                   uint32_t value) {
+  [[nodiscard]] static inline uint8_t *ESPHOME_ALWAYS_INLINE
+  encode_varint_raw_short(uint8_t *__restrict__ pos PROTO_ENCODE_DEBUG_PARAM, uint32_t value) {
     if (value < VARINT_MAX_1_BYTE) [[likely]] {
       PROTO_ENCODE_CHECK_BOUNDS(pos, 1);
       *pos++ = static_cast<uint8_t>(value);
-      return;
+      return pos;
     }
     if (value < VARINT_MAX_2_BYTE) [[likely]] {
       PROTO_ENCODE_CHECK_BOUNDS(pos, 2);
       *pos++ = static_cast<uint8_t>(value | 0x80);
       *pos++ = static_cast<uint8_t>(value >> 7);
-      return;
+      return pos;
     }
-    encode_varint_raw_loop(pos PROTO_ENCODE_DEBUG_ARG, value);
+    return encode_varint_raw_loop(pos PROTO_ENCODE_DEBUG_ARG, value);
   }
-  static inline void ESPHOME_ALWAYS_INLINE encode_varint_raw_64(uint8_t *__restrict__ &pos PROTO_ENCODE_DEBUG_PARAM,
-                                                                uint64_t value) {
+  [[nodiscard]] static inline uint8_t *ESPHOME_ALWAYS_INLINE
+  encode_varint_raw_64(uint8_t *__restrict__ pos PROTO_ENCODE_DEBUG_PARAM, uint64_t value) {
     if (value < VARINT_MAX_1_BYTE) [[likely]] {
       PROTO_ENCODE_CHECK_BOUNDS(pos, 1);
       *pos++ = static_cast<uint8_t>(value);
-      return;
+      return pos;
     }
-    encode_varint_raw_loop(pos PROTO_ENCODE_DEBUG_ARG, value);
+    return encode_varint_raw_loop(pos PROTO_ENCODE_DEBUG_ARG, value);
   }
   /// Encode a 48-bit MAC address (stored in a uint64) as varint.
   /// Real MAC addresses occupy the full 48 bits (OUI in upper 24), so the
   /// fast path -- any non-zero bit in the top 6 of 48 -- emits exactly 7 bytes
   /// with no per-byte branch. Falls back to the general loop otherwise.
   /// Caller must guarantee value fits in 48 bits (checked in debug builds).
-  static inline void ESPHOME_ALWAYS_INLINE encode_varint_raw_48bit(uint8_t *__restrict__ &pos PROTO_ENCODE_DEBUG_PARAM,
-                                                                   uint64_t value) {
+  [[nodiscard]] static inline uint8_t *ESPHOME_ALWAYS_INLINE
+  encode_varint_raw_48bit(uint8_t *__restrict__ pos PROTO_ENCODE_DEBUG_PARAM, uint64_t value) {
 #ifdef ESPHOME_DEBUG_API
     assert(value < (1ULL << (MAC_ADDRESS_SIZE * 8)) && "encode_varint_raw_48bit: value exceeds 48 bits");
 #endif
@@ -363,38 +379,39 @@ class ProtoEncode {
       pos[4] = static_cast<uint8_t>((value >> 28) | 0x80);
       pos[5] = static_cast<uint8_t>((value >> 35) | 0x80);
       pos[6] = static_cast<uint8_t>(value >> 42);
-      pos += 7;
-      return;
+      return pos + 7;
     }
-    encode_varint_raw_64(pos PROTO_ENCODE_DEBUG_ARG, value);
+    return encode_varint_raw_64(pos PROTO_ENCODE_DEBUG_ARG, value);
   }
-  static inline void ESPHOME_ALWAYS_INLINE encode_field_raw(uint8_t *__restrict__ &pos PROTO_ENCODE_DEBUG_PARAM,
-                                                            uint32_t field_id, uint32_t type) {
-    encode_varint_raw(pos PROTO_ENCODE_DEBUG_ARG, (field_id << 3) | type);
+  [[nodiscard]] static inline uint8_t *ESPHOME_ALWAYS_INLINE
+  encode_field_raw(uint8_t *__restrict__ pos PROTO_ENCODE_DEBUG_PARAM, uint32_t field_id, uint32_t type) {
+    return encode_varint_raw(pos PROTO_ENCODE_DEBUG_ARG, proto_tag(field_id, type));
   }
   /// Write a single precomputed tag byte. Tag must be < 128.
-  static inline void ESPHOME_ALWAYS_INLINE write_raw_byte(uint8_t *__restrict__ &pos PROTO_ENCODE_DEBUG_PARAM,
-                                                          uint8_t b) {
+  [[nodiscard]] static inline uint8_t *ESPHOME_ALWAYS_INLINE
+  write_raw_byte(uint8_t *__restrict__ pos PROTO_ENCODE_DEBUG_PARAM, uint8_t b) {
     PROTO_ENCODE_CHECK_BOUNDS(pos, 1);
     *pos++ = b;
+    return pos;
   }
   /// Reserve one byte for later backpatch (e.g., sub-message length).
   /// Advances pos past the reserved byte without writing a value.
-  static inline void ESPHOME_ALWAYS_INLINE reserve_byte(uint8_t *__restrict__ &pos PROTO_ENCODE_DEBUG_PARAM) {
+  [[nodiscard]] static inline uint8_t *ESPHOME_ALWAYS_INLINE
+  reserve_byte(uint8_t *__restrict__ pos PROTO_ENCODE_DEBUG_PARAM) {
     PROTO_ENCODE_CHECK_BOUNDS(pos, 1);
-    pos++;
+    return pos + 1;
   }
   /// Write raw bytes to the buffer (no tag, no length prefix).
-  static inline void ESPHOME_ALWAYS_INLINE encode_raw(uint8_t *__restrict__ &pos PROTO_ENCODE_DEBUG_PARAM,
-                                                      const void *data, size_t len) {
+  [[nodiscard]] static inline uint8_t *ESPHOME_ALWAYS_INLINE
+  encode_raw(uint8_t *__restrict__ pos PROTO_ENCODE_DEBUG_PARAM, const void *data, size_t len) {
     PROTO_ENCODE_CHECK_BOUNDS(pos, len);
     std::memcpy(pos, data, len);
-    pos += len;
+    return pos + len;
   }
   /// Encode tag + 1-byte length + raw string data. For strings with max_data_length < 128.
   /// Tag must be a single-byte varint (< 128). Always encodes (no zero check).
-  static inline void encode_short_string_force(uint8_t *__restrict__ &pos PROTO_ENCODE_DEBUG_PARAM, uint8_t tag,
-                                               const StringRef &ref) {
+  [[nodiscard]] static inline uint8_t *encode_short_string_force(uint8_t *__restrict__ pos PROTO_ENCODE_DEBUG_PARAM,
+                                                                 uint8_t tag, const StringRef &ref) {
 #ifdef ESPHOME_DEBUG_API
     assert(ref.size() < 128 && "encode_short_string_force: string exceeds max_data_length < 128");
 #endif
@@ -402,137 +419,191 @@ class ProtoEncode {
     pos[0] = tag;
     pos[1] = static_cast<uint8_t>(ref.size());
     std::memcpy(pos + 2, ref.c_str(), ref.size());
-    pos += 2 + ref.size();
+    return pos + 2 + ref.size();
   }
-  /// Write a precomputed tag byte + 32-bit value in one operation.
-  static inline void ESPHOME_ALWAYS_INLINE write_tag_and_fixed32(uint8_t *__restrict__ &pos PROTO_ENCODE_DEBUG_PARAM,
-                                                                 uint8_t tag, uint32_t value) {
+  /// Write a precomputed tag byte + 32-bit value. Outlined on embedded: one copy beats inline stores per field.
+  [[nodiscard]] static PROTO_OUTLINE_FOR_SIZE uint8_t *write_tag_and_fixed32(
+      uint8_t *__restrict__ pos PROTO_ENCODE_DEBUG_PARAM, uint8_t tag, uint32_t value) {
     PROTO_ENCODE_CHECK_BOUNDS(pos, 5);
     pos[0] = tag;
-#if __BYTE_ORDER__ == __ORDER_LITTLE_ENDIAN__
-    std::memcpy(pos + 1, &value, 4);
-#else
-    pos[1] = static_cast<uint8_t>(value & 0xFF);
-    pos[2] = static_cast<uint8_t>((value >> 8) & 0xFF);
-    pos[3] = static_cast<uint8_t>((value >> 16) & 0xFF);
-    pos[4] = static_cast<uint8_t>((value >> 24) & 0xFF);
-#endif
-    pos += 5;
+    write_fixed32_le(pos + 1, value);
+    return pos + 5;
   }
-  static inline void encode_string(uint8_t *__restrict__ &pos PROTO_ENCODE_DEBUG_PARAM, uint32_t field_id,
-                                   const char *string, size_t len, bool force = false) {
-    if (len == 0 && !force)
-      return;
-    encode_field_raw(pos PROTO_ENCODE_DEBUG_ARG, field_id, 2);  // type 2: Length-delimited string
+  [[nodiscard]] static inline uint8_t *encode_string_force(uint8_t *__restrict__ pos PROTO_ENCODE_DEBUG_PARAM,
+                                                           uint32_t field_id, const char *string, size_t len) {
+    pos = encode_field_raw(pos PROTO_ENCODE_DEBUG_ARG, field_id, 2);  // type 2: Length-delimited string
     // NOLINTNEXTLINE(readability-inconsistent-ifelse-braces) -- false positive on [[likely]] attribute
     if (len < VARINT_MAX_1_BYTE) [[likely]] {
       PROTO_ENCODE_CHECK_BOUNDS(pos, 1 + len);
       *pos++ = static_cast<uint8_t>(len);
     } else {
-      encode_varint_raw_loop(pos PROTO_ENCODE_DEBUG_ARG, len);
+      pos = encode_varint_raw_loop(pos PROTO_ENCODE_DEBUG_ARG, len);
       PROTO_ENCODE_CHECK_BOUNDS(pos, len);
     }
     std::memcpy(pos, string, len);
-    pos += len;
+    return pos + len;
   }
-  static inline void encode_string(uint8_t *__restrict__ &pos PROTO_ENCODE_DEBUG_PARAM, uint32_t field_id,
-                                   const std::string &value, bool force = false) {
-    encode_string(pos PROTO_ENCODE_DEBUG_ARG, field_id, value.data(), value.size(), force);
+  [[nodiscard]] static inline uint8_t *encode_string(uint8_t *__restrict__ pos PROTO_ENCODE_DEBUG_PARAM,
+                                                     uint32_t field_id, const char *string, size_t len) {
+    if (len == 0)
+      return pos;
+    return encode_string_force(pos PROTO_ENCODE_DEBUG_ARG, field_id, string, len);
   }
-  static inline void encode_string(uint8_t *__restrict__ &pos PROTO_ENCODE_DEBUG_PARAM, uint32_t field_id,
-                                   const StringRef &ref, bool force = false) {
-    encode_string(pos PROTO_ENCODE_DEBUG_ARG, field_id, ref.c_str(), ref.size(), force);
+  [[nodiscard]] static inline uint8_t *encode_string_force(uint8_t *__restrict__ pos PROTO_ENCODE_DEBUG_PARAM,
+                                                           uint32_t field_id, const std::string &value) {
+    return encode_string_force(pos PROTO_ENCODE_DEBUG_ARG, field_id, value.data(), value.size());
   }
-  static inline void encode_bytes(uint8_t *__restrict__ &pos PROTO_ENCODE_DEBUG_PARAM, uint32_t field_id,
-                                  const uint8_t *data, size_t len, bool force = false) {
-    encode_string(pos PROTO_ENCODE_DEBUG_ARG, field_id, reinterpret_cast<const char *>(data), len, force);
+  [[nodiscard]] static inline uint8_t *encode_string(uint8_t *__restrict__ pos PROTO_ENCODE_DEBUG_PARAM,
+                                                     uint32_t field_id, const StringRef &ref) {
+    return encode_string(pos PROTO_ENCODE_DEBUG_ARG, field_id, ref.c_str(), ref.size());
   }
-  static inline void encode_uint32(uint8_t *__restrict__ &pos PROTO_ENCODE_DEBUG_PARAM, uint32_t field_id,
-                                   uint32_t value, bool force = false) {
-    if (value == 0 && !force)
-      return;
-    encode_field_raw(pos PROTO_ENCODE_DEBUG_ARG, field_id, 0);
-    encode_varint_raw(pos PROTO_ENCODE_DEBUG_ARG, value);
+  [[nodiscard]] static inline uint8_t *encode_string_force(uint8_t *__restrict__ pos PROTO_ENCODE_DEBUG_PARAM,
+                                                           uint32_t field_id, const StringRef &ref) {
+    return encode_string_force(pos PROTO_ENCODE_DEBUG_ARG, field_id, ref.c_str(), ref.size());
   }
-  static inline void encode_uint64(uint8_t *__restrict__ &pos PROTO_ENCODE_DEBUG_PARAM, uint32_t field_id,
-                                   uint64_t value, bool force = false) {
-    if (value == 0 && !force)
-      return;
-    encode_field_raw(pos PROTO_ENCODE_DEBUG_ARG, field_id, 0);
-    encode_varint_raw_64(pos PROTO_ENCODE_DEBUG_ARG, value);
+  [[nodiscard]] static inline uint8_t *encode_bytes(uint8_t *__restrict__ pos PROTO_ENCODE_DEBUG_PARAM,
+                                                    uint32_t field_id, const uint8_t *data, size_t len) {
+    return encode_string(pos PROTO_ENCODE_DEBUG_ARG, field_id, reinterpret_cast<const char *>(data), len);
   }
-  static inline void encode_bool(uint8_t *__restrict__ &pos PROTO_ENCODE_DEBUG_PARAM, uint32_t field_id, bool value,
-                                 bool force = false) {
-    if (!value && !force)
-      return;
-    encode_field_raw(pos PROTO_ENCODE_DEBUG_ARG, field_id, 0);
+  [[nodiscard]] static inline uint8_t *encode_bytes_force(uint8_t *__restrict__ pos PROTO_ENCODE_DEBUG_PARAM,
+                                                          uint32_t field_id, const uint8_t *data, size_t len) {
+    return encode_string_force(pos PROTO_ENCODE_DEBUG_ARG, field_id, reinterpret_cast<const char *>(data), len);
+  }
+  [[nodiscard]] static inline uint8_t *encode_uint32_force(uint8_t *__restrict__ pos PROTO_ENCODE_DEBUG_PARAM,
+                                                           uint32_t field_id, uint32_t value) {
+    pos = encode_field_raw(pos PROTO_ENCODE_DEBUG_ARG, field_id, 0);
+    return encode_varint_raw(pos PROTO_ENCODE_DEBUG_ARG, value);
+  }
+  [[nodiscard]] static inline uint8_t *encode_uint32(uint8_t *__restrict__ pos PROTO_ENCODE_DEBUG_PARAM,
+                                                     uint32_t field_id, uint32_t value) {
+    if (value == 0)
+      return pos;
+    return encode_uint32_force(pos PROTO_ENCODE_DEBUG_ARG, field_id, value);
+  }
+  [[nodiscard]] static inline uint8_t *encode_uint64_force(uint8_t *__restrict__ pos PROTO_ENCODE_DEBUG_PARAM,
+                                                           uint32_t field_id, uint64_t value) {
+    pos = encode_field_raw(pos PROTO_ENCODE_DEBUG_ARG, field_id, 0);
+    return encode_varint_raw_64(pos PROTO_ENCODE_DEBUG_ARG, value);
+  }
+  [[nodiscard]] static inline uint8_t *encode_uint64(uint8_t *__restrict__ pos PROTO_ENCODE_DEBUG_PARAM,
+                                                     uint32_t field_id, uint64_t value) {
+    if (value == 0)
+      return pos;
+    return encode_uint64_force(pos PROTO_ENCODE_DEBUG_ARG, field_id, value);
+  }
+  [[nodiscard]] static inline uint8_t *encode_bool_force(uint8_t *__restrict__ pos PROTO_ENCODE_DEBUG_PARAM,
+                                                         uint32_t field_id, bool value) {
+    pos = encode_field_raw(pos PROTO_ENCODE_DEBUG_ARG, field_id, 0);
     PROTO_ENCODE_CHECK_BOUNDS(pos, 1);
     *pos++ = value ? 0x01 : 0x00;
+    return pos;
   }
-  static inline void encode_fixed32(uint8_t *__restrict__ &pos PROTO_ENCODE_DEBUG_PARAM, uint32_t field_id,
-                                    uint32_t value, bool force = false) {
-    if (value == 0 && !force)
-      return;
-    encode_field_raw(pos PROTO_ENCODE_DEBUG_ARG, field_id, 5);
+  [[nodiscard]] static inline uint8_t *encode_bool(uint8_t *__restrict__ pos PROTO_ENCODE_DEBUG_PARAM,
+                                                   uint32_t field_id, bool value) {
+    if (!value)
+      return pos;
+    return encode_bool_force(pos PROTO_ENCODE_DEBUG_ARG, field_id, value);
+  }
+  /// Tag + fixed32 for multi-byte tags; single-byte tags use write_tag_and_fixed32.
+  [[nodiscard]] static PROTO_OUTLINE_FOR_SIZE uint8_t *encode_fixed32_force(
+      uint8_t *__restrict__ pos PROTO_ENCODE_DEBUG_PARAM, uint32_t field_id, uint32_t value) {
+    pos = encode_field_raw(pos PROTO_ENCODE_DEBUG_ARG, field_id, 5);
     PROTO_ENCODE_CHECK_BOUNDS(pos, 4);
-#if __BYTE_ORDER__ == __ORDER_LITTLE_ENDIAN__
-    std::memcpy(pos, &value, 4);
-    pos += 4;
-#else
-    *pos++ = (value >> 0) & 0xFF;
-    *pos++ = (value >> 8) & 0xFF;
-    *pos++ = (value >> 16) & 0xFF;
-    *pos++ = (value >> 24) & 0xFF;
-#endif
+    write_fixed32_le(pos, value);
+    return pos + 4;
+  }
+  [[nodiscard]] static inline uint8_t *encode_fixed32(uint8_t *__restrict__ pos PROTO_ENCODE_DEBUG_PARAM,
+                                                      uint32_t field_id, uint32_t value) {
+    if (value == 0)
+      return pos;
+    return encode_fixed32_force(pos PROTO_ENCODE_DEBUG_ARG, field_id, value);
   }
   // NOTE: Wire type 1 (64-bit fixed: double, fixed64, sfixed64) is intentionally
   // not supported to reduce overhead on embedded systems. All ESPHome devices are
   // 32-bit microcontrollers where 64-bit operations are expensive. If 64-bit support
   // is needed in the future, the necessary encoding/decoding functions must be added.
-  static inline void encode_float(uint8_t *__restrict__ &pos PROTO_ENCODE_DEBUG_PARAM, uint32_t field_id, float value,
-                                  bool force = false) {
-    uint32_t raw = float_to_raw(value);
-    if (raw == 0 && !force)
-      return;
-    encode_fixed32(pos PROTO_ENCODE_DEBUG_ARG, field_id, raw);
+  [[nodiscard]] static inline uint8_t *encode_float(uint8_t *__restrict__ pos PROTO_ENCODE_DEBUG_PARAM,
+                                                    uint32_t field_id, float value) {
+    return encode_fixed32(pos PROTO_ENCODE_DEBUG_ARG, field_id, float_to_raw(value));
   }
-  static inline void encode_int32(uint8_t *__restrict__ &pos PROTO_ENCODE_DEBUG_PARAM, uint32_t field_id, int32_t value,
-                                  bool force = false) {
+  [[nodiscard]] static inline uint8_t *encode_float_force(uint8_t *__restrict__ pos PROTO_ENCODE_DEBUG_PARAM,
+                                                          uint32_t field_id, float value) {
+    return encode_fixed32_force(pos PROTO_ENCODE_DEBUG_ARG, field_id, float_to_raw(value));
+  }
+  [[nodiscard]] static inline uint8_t *encode_int32_force(uint8_t *__restrict__ pos PROTO_ENCODE_DEBUG_PARAM,
+                                                          uint32_t field_id, int32_t value) {
     if (value < 0) {
       // negative int32 is always 10 byte long
-      encode_uint64(pos PROTO_ENCODE_DEBUG_ARG, field_id, static_cast<uint64_t>(value), force);
-      return;
+      return encode_uint64_force(pos PROTO_ENCODE_DEBUG_ARG, field_id, static_cast<uint64_t>(value));
     }
-    encode_uint32(pos PROTO_ENCODE_DEBUG_ARG, field_id, static_cast<uint32_t>(value), force);
+    return encode_uint32_force(pos PROTO_ENCODE_DEBUG_ARG, field_id, static_cast<uint32_t>(value));
   }
-  static inline void encode_int64(uint8_t *__restrict__ &pos PROTO_ENCODE_DEBUG_PARAM, uint32_t field_id, int64_t value,
-                                  bool force = false) {
-    encode_uint64(pos PROTO_ENCODE_DEBUG_ARG, field_id, static_cast<uint64_t>(value), force);
+  [[nodiscard]] static inline uint8_t *encode_int32(uint8_t *__restrict__ pos PROTO_ENCODE_DEBUG_PARAM,
+                                                    uint32_t field_id, int32_t value) {
+    if (value == 0)
+      return pos;
+    return encode_int32_force(pos PROTO_ENCODE_DEBUG_ARG, field_id, value);
   }
-  static inline void encode_sint32(uint8_t *__restrict__ &pos PROTO_ENCODE_DEBUG_PARAM, uint32_t field_id,
-                                   int32_t value, bool force = false) {
-    encode_uint32(pos PROTO_ENCODE_DEBUG_ARG, field_id, encode_zigzag32(value), force);
+  [[nodiscard]] static inline uint8_t *encode_int64(uint8_t *__restrict__ pos PROTO_ENCODE_DEBUG_PARAM,
+                                                    uint32_t field_id, int64_t value) {
+    return encode_uint64(pos PROTO_ENCODE_DEBUG_ARG, field_id, static_cast<uint64_t>(value));
   }
-  static inline void encode_sint64(uint8_t *__restrict__ &pos PROTO_ENCODE_DEBUG_PARAM, uint32_t field_id,
-                                   int64_t value, bool force = false) {
-    encode_uint64(pos PROTO_ENCODE_DEBUG_ARG, field_id, encode_zigzag64(value), force);
+  [[nodiscard]] static inline uint8_t *encode_int64_force(uint8_t *__restrict__ pos PROTO_ENCODE_DEBUG_PARAM,
+                                                          uint32_t field_id, int64_t value) {
+    return encode_uint64_force(pos PROTO_ENCODE_DEBUG_ARG, field_id, static_cast<uint64_t>(value));
   }
-  /// Sub-message encoding: sync pos to buffer, delegate, get pos from return value.
+  [[nodiscard]] static inline uint8_t *encode_sint32(uint8_t *__restrict__ pos PROTO_ENCODE_DEBUG_PARAM,
+                                                     uint32_t field_id, int32_t value) {
+    return encode_uint32(pos PROTO_ENCODE_DEBUG_ARG, field_id, encode_zigzag32(value));
+  }
+  [[nodiscard]] static inline uint8_t *encode_sint32_force(uint8_t *__restrict__ pos PROTO_ENCODE_DEBUG_PARAM,
+                                                           uint32_t field_id, int32_t value) {
+    return encode_uint32_force(pos PROTO_ENCODE_DEBUG_ARG, field_id, encode_zigzag32(value));
+  }
+  [[nodiscard]] static inline uint8_t *encode_sint64(uint8_t *__restrict__ pos PROTO_ENCODE_DEBUG_PARAM,
+                                                     uint32_t field_id, int64_t value) {
+    return encode_uint64(pos PROTO_ENCODE_DEBUG_ARG, field_id, encode_zigzag64(value));
+  }
+  [[nodiscard]] static inline uint8_t *encode_sint64_force(uint8_t *__restrict__ pos PROTO_ENCODE_DEBUG_PARAM,
+                                                           uint32_t field_id, int64_t value) {
+    return encode_uint64_force(pos PROTO_ENCODE_DEBUG_ARG, field_id, encode_zigzag64(value));
+  }
+  /// Sub-message encoding: sync pos to buffer, delegate, read the cursor back.
   template<typename T>
-  static inline void encode_sub_message(uint8_t *__restrict__ &pos PROTO_ENCODE_DEBUG_PARAM, ProtoWriteBuffer &buffer,
-                                        uint32_t field_id, const T &value) {
+  [[nodiscard]] static inline uint8_t *encode_sub_message(uint8_t *__restrict__ pos PROTO_ENCODE_DEBUG_PARAM,
+                                                          ProtoWriteBuffer &buffer, uint32_t field_id, const T &value) {
     buffer.set_pos(pos);
     buffer.encode_sub_message(field_id, value);
-    pos = buffer.get_pos();
+    return buffer.get_pos();
   }
   template<typename T>
-  static inline void encode_optional_sub_message(uint8_t *__restrict__ &pos PROTO_ENCODE_DEBUG_PARAM,
-                                                 ProtoWriteBuffer &buffer, uint32_t field_id, const T &value) {
+  [[nodiscard]] static inline uint8_t *encode_optional_sub_message(uint8_t *__restrict__ pos PROTO_ENCODE_DEBUG_PARAM,
+                                                                   ProtoWriteBuffer &buffer, uint32_t field_id,
+                                                                   const T &value) {
     buffer.set_pos(pos);
     buffer.encode_optional_sub_message(field_id, value);
-    pos = buffer.get_pos();
+    return buffer.get_pos();
+  }
+
+ private:
+  /// Unaligned little endian store of four bytes: byte stores where the outlined helper lives (ESP-IDF, ARM
+  /// without unaligned access), otherwise a memcpy the compiler folds into one store. Callers bounds check
+  /// and advance the cursor themselves.
+  static inline void ESPHOME_ALWAYS_INLINE write_fixed32_le(uint8_t *__restrict__ pos, uint32_t value) {
+    if constexpr (PROTO_FIXED32_BYTE_STORES) {
+      // Spelled out so the outlined helper does not itself become a memcpy call
+      pos[0] = static_cast<uint8_t>(value);
+      pos[1] = static_cast<uint8_t>(value >> 8);
+      pos[2] = static_cast<uint8_t>(value >> 16);
+      pos[3] = static_cast<uint8_t>(value >> 24);
+    } else {
+      const uint32_t le = convert_little_endian(value);
+      __builtin_memcpy(pos, &le, 4);
+    }
   }
 };
+#undef PROTO_OUTLINE_FOR_SIZE
+#undef PROTO_FIXED32_BYTE_STORES
 
 #ifdef HAS_PROTO_MESSAGE_DUMP
 /**
@@ -624,11 +695,12 @@ class DumpBuffer {
 
 class ProtoMessage {
  public:
-  // Non-virtual defaults for messages with no fields.
-  // Concrete message classes hide these with their own implementations.
-  // All call sites use templates to preserve the concrete type, so virtual
-  // dispatch is not needed. This eliminates per-message vtable entries for
-  // encode/calculate_size, saving ~1.3 KB of flash across all message types.
+  // Non-virtual defaults for messages with no fields; generated classes hide all four. The
+  // static encode_msg/calc_size_msg take const void * so &T::encode_msg needs no thunk.
+  static uint8_t *encode_msg(const void *self, ProtoWriteBuffer &buffer PROTO_ENCODE_DEBUG_PARAM) {
+    return buffer.get_pos();
+  }
+  static uint32_t calc_size_msg(const void *self) { return 0; }
   uint8_t *encode(ProtoWriteBuffer &buffer PROTO_ENCODE_DEBUG_PARAM) const { return buffer.get_pos(); }
   uint32_t calculate_size() const { return 0; }
 #ifdef HAS_PROTO_MESSAGE_DUMP
@@ -663,10 +735,10 @@ class ProtoDecodableMessage : public ProtoMessage {
 
  protected:
   ~ProtoDecodableMessage() = default;
-  virtual bool decode_varint(uint32_t field_id, proto_varint_value_t value) { return false; }
-  virtual bool decode_length(uint32_t field_id, ProtoLengthDelimited value) { return false; }
-  virtual bool decode_32bit(uint32_t field_id, Proto32Bit value) { return false; }
-  // NOTE: decode_64bit removed - wire type 1 not supported
+  /// Store one decoded field; \p scalar is the varint or fixed32 value, or the length of the
+  /// length-delimited payload at \p data. An unknown field or wrong wire type matches no case and is skipped.
+  /// Three register arguments keep the decode loop free of spills.
+  virtual void decode_field(uint32_t tag, const uint8_t *data, proto_varint_value_t scalar) {}
 };
 
 class ProtoSize {
@@ -792,7 +864,7 @@ class ProtoSize {
    * @return The number of bytes needed to encode the field ID and wire type
    */
   static constexpr uint32_t field(uint32_t field_id, uint32_t type) {
-    uint32_t tag = (field_id << 3) | (type & WIRE_TYPE_MASK);
+    uint32_t tag = proto_tag(field_id, type & WIRE_TYPE_MASK);
     return varint(tag);
   }
 
@@ -876,24 +948,14 @@ class ProtoSize {
 
 // Implementation of methods that depend on ProtoSize being fully defined
 
-// Encode thunk — converts void* back to concrete type for direct encode() call
-template<typename T> uint8_t *proto_encode_msg(const void *msg, ProtoWriteBuffer &buf PROTO_ENCODE_DEBUG_PARAM) {
-  return static_cast<const T *>(msg)->encode(buf PROTO_ENCODE_DEBUG_ARG);
-}
-
 // Thin template wrapper; delegates to non-template core in proto.cpp.
 template<typename T> inline void ProtoWriteBuffer::encode_sub_message(uint32_t field_id, const T &value) {
-  this->encode_sub_message(field_id, &value, &proto_encode_msg<T>);
+  this->encode_sub_message(field_id, &value, &T::encode_msg);
 }
 
 // Thin template wrapper; delegates to non-template core.
 template<typename T> inline void ProtoWriteBuffer::encode_optional_sub_message(uint32_t field_id, const T &value) {
-  this->encode_optional_sub_message(field_id, value.calculate_size(), &value, &proto_encode_msg<T>);
-}
-
-// Template decode_to_message - preserves concrete type so decode() resolves statically
-template<typename T> void ProtoLengthDelimited::decode_to_message(T &msg) const {
-  msg.decode(this->value_, this->length_);
+  this->encode_optional_sub_message(field_id, T::calc_size_msg(&value), &value, &T::encode_msg);
 }
 
 template<typename T> const char *proto_enum_to_string(T value);

esphome/components/audio/audio_reader.cpp

@@ -58,6 +58,9 @@ esp_err_t AudioReader::add_sink(const std::weak_ptr<ring_buffer::RingBuffer> &ou
   if (current_audio_file_ != nullptr) {
     // A transfer buffer isn't ncessary for a local file
     this->file_ring_buffer_ = output_ring_buffer.lock();
+    if (this->file_ring_buffer_ == nullptr) {
+      return ESP_ERR_INVALID_STATE;
+    }
     return ESP_OK;
   }
 

esphome/components/audio/audio_transfer_buffer.cpp

@@ -51,14 +51,14 @@ void AudioTransferBuffer::increase_buffer_length(size_t bytes) { this->buffer_le
 
 void AudioTransferBuffer::clear_buffered_data() {
   this->buffer_length_ = 0;
-  if (this->ring_buffer_.use_count() > 0) {
+  if (this->ring_buffer_ != nullptr) {
     this->ring_buffer_->reset();
   }
 }
 
 void AudioSinkTransferBuffer::clear_buffered_data() {
   this->buffer_length_ = 0;
-  if (this->ring_buffer_.use_count() > 0) {
+  if (this->ring_buffer_ != nullptr) {
     this->ring_buffer_->reset();
   }
 #ifdef USE_SPEAKER
@@ -69,7 +69,7 @@ void AudioSinkTransferBuffer::clear_buffered_data() {
 }
 
 bool AudioTransferBuffer::has_buffered_data() const {
-  if (this->ring_buffer_.use_count() > 0) {
+  if (this->ring_buffer_ != nullptr) {
     return ((this->ring_buffer_->available() > 0) || (this->available() > 0));
   }
   return (this->available() > 0);
@@ -144,7 +144,7 @@ size_t AudioSourceTransferBuffer::transfer_data_from_source(TickType_t ticks_to_
   size_t bytes_to_read = AudioTransferBuffer::free();
   size_t bytes_read = 0;
   if (bytes_to_read > 0) {
-    if (this->ring_buffer_.use_count() > 0) {
+    if (this->ring_buffer_ != nullptr) {
       bytes_read = this->ring_buffer_->read((void *) this->get_buffer_end(), bytes_to_read, ticks_to_wait);
     }
 
@@ -161,7 +161,7 @@ size_t AudioSinkTransferBuffer::transfer_data_to_sink(TickType_t ticks_to_wait,
       bytes_written = this->speaker_->play(this->data_start_, this->available(), ticks_to_wait);
     } else
 #endif
-        if (this->ring_buffer_.use_count() > 0) {
+        if (this->ring_buffer_ != nullptr) {
       bytes_written =
           this->ring_buffer_->write_without_replacement((void *) this->data_start_, this->available(), ticks_to_wait);
     } else if (this->sink_callback_ != nullptr) {
@@ -186,7 +186,7 @@ bool AudioSinkTransferBuffer::has_buffered_data() const {
     return (this->speaker_->has_buffered_data() || (this->available() > 0));
   }
 #endif
-  if (this->ring_buffer_.use_count() > 0) {
+  if (this->ring_buffer_ != nullptr) {
     return ((this->ring_buffer_->available() > 0) || (this->available() > 0));
   }
   return (this->available() > 0);

esphome/components/deep_sleep/deep_sleep_bk72xx.cpp

@@ -44,7 +44,7 @@ bool DeepSleepComponent::prepare_to_sleep_() {
           this->status_set_warning();
           ESP_LOGV(TAG, "Waiting for pin to switch state to enter deep sleep...");
         }
-        this->next_enter_deep_sleep_ = true;
+        this->defer_sleep_();
         return false;
       }
     }

esphome/components/deep_sleep/deep_sleep_component.cpp

@@ -17,6 +17,7 @@ void DeepSleepComponent::setup() {
 
 void DeepSleepComponent::schedule_sleep_() {
   this->next_enter_deep_sleep_ = false;
+  this->disable_loop();
   const optional<uint32_t> run_duration = get_run_duration_();
   if (run_duration.has_value()) {
     ESP_LOGI(TAG, "Scheduling in %" PRIu32 " ms", *run_duration);
@@ -45,7 +46,7 @@ void DeepSleepComponent::loop() {
 
 void DeepSleepComponent::begin_sleep(bool manual) {
   if (this->prevent_ && !manual) {
-    this->next_enter_deep_sleep_ = true;
+    this->defer_sleep_();
     return;
   }
 

esphome/components/deep_sleep/deep_sleep_component.h

@@ -190,6 +190,11 @@ class DeepSleepComponent final : public Component {
   void schedule_sleep_();
   bool should_teardown_();
 
+  void defer_sleep_() {
+    this->next_enter_deep_sleep_ = true;
+    this->enable_loop();
+  }
+
 #ifdef USE_BK72XX
   bool pin_prevents_sleep_(WakeUpPinItem &pin_item) const;
   bool get_real_pin_state_(InternalGPIOPin &pin) const { return (pin.digital_read() ^ pin.is_inverted()); }

esphome/components/deep_sleep/deep_sleep_esp32.cpp

@@ -100,7 +100,7 @@ bool DeepSleepComponent::prepare_to_sleep_() {
       this->status_set_warning();
       ESP_LOGW(TAG, "Waiting for wakeup pin state change");
     }
-    this->next_enter_deep_sleep_ = true;
+    this->defer_sleep_();
     return false;
   }
   return true;

esphome/components/es7210/es7210.cpp

@@ -153,13 +153,14 @@ bool ES7210::configure_mic_gain_() {
   ES7210_ERROR_CHECK(this->es7210_update_reg_bit_(ES7210_MIC2_GAIN_REG44, 0x0f, regv));
 
   // Configure mic 3
-  ES7210_ERROR_CHECK(this->es7210_update_reg_bit_(ES7210_CLOCK_OFF_REG01, 0x0b, 0x00));
+  // MIC3 uses the ADC3/4 and MIC3/4 clock domains (bits 2 and 4), not the MIC1/2 domains.
+  ES7210_ERROR_CHECK(this->es7210_update_reg_bit_(ES7210_CLOCK_OFF_REG01, 0x15, 0x00));
   ES7210_ERROR_CHECK(this->write_byte(ES7210_MIC34_POWER_REG4C, 0x00));
   ES7210_ERROR_CHECK(this->es7210_update_reg_bit_(ES7210_MIC3_GAIN_REG45, 0x10, 0x10));
   ES7210_ERROR_CHECK(this->es7210_update_reg_bit_(ES7210_MIC3_GAIN_REG45, 0x0f, regv));
 
   // Configure mic 4
-  ES7210_ERROR_CHECK(this->es7210_update_reg_bit_(ES7210_CLOCK_OFF_REG01, 0x0b, 0x00));
+  ES7210_ERROR_CHECK(this->es7210_update_reg_bit_(ES7210_CLOCK_OFF_REG01, 0x15, 0x00));
   ES7210_ERROR_CHECK(this->write_byte(ES7210_MIC34_POWER_REG4C, 0x00));
   ES7210_ERROR_CHECK(this->es7210_update_reg_bit_(ES7210_MIC4_GAIN_REG46, 0x10, 0x10));
   ES7210_ERROR_CHECK(this->es7210_update_reg_bit_(ES7210_MIC4_GAIN_REG46, 0x0f, regv));

esphome/components/esphome/ota/ota_esphome.cpp

@@ -41,7 +41,10 @@ const noise::NoiseContext &ESPHomeOTAComponent::noise_context_() const {
 #endif
 static constexpr uint16_t OTA_BLOCK_SIZE = 8192;
 static constexpr uint32_t OTA_SOCKET_TIMEOUT_HANDSHAKE = 20000;  // milliseconds for initial handshake
-static constexpr uint32_t OTA_SOCKET_TIMEOUT_DATA = 90000;       // milliseconds for data transfer
+// Milliseconds for data transfer. Covers the lwIP retransmit run seen in
+// practice for a lost chunk ack (1.5 + 3 + 6 + 12 + 24 + 48 s); the CLI waits
+// longer (espota2.DATA_PHASE_TIMEOUT) so the device is free before it retries
+static constexpr uint32_t OTA_SOCKET_TIMEOUT_DATA = 105000;
 
 // Single-instance pointer — multi-port configs are rejected in final_validate.
 // NOLINTNEXTLINE(cppcoreguidelines-avoid-non-const-global-variables)

esphome/components/i2s_audio/speaker/i2s_audio_speaker.cpp

@@ -118,21 +118,24 @@ void I2SAudioSpeakerBase::loop() {
         break;
       }
 
+      // Still starting up or winding down from a previous run
+      if ((this->tx_handle_ != nullptr) || (this->speaker_task_handle_ != nullptr)) {
+        break;
+      }
+
       if (this->start_i2s_driver(this->audio_stream_info_) != ESP_OK) {
         ESP_LOGE(TAG, "Driver failed to start; retrying in 1 second");
         this->status_momentary_error("driver-failure", 1000);
         break;
       }
 
-      if (this->speaker_task_handle_ == nullptr) {
-        xTaskCreate(I2SAudioSpeakerBase::speaker_task, "speaker_task", TASK_STACK_SIZE, (void *) this, TASK_PRIORITY,
-                    &this->speaker_task_handle_);
+      xTaskCreate(I2SAudioSpeakerBase::speaker_task, "speaker_task", TASK_STACK_SIZE, (void *) this, TASK_PRIORITY,
+                  &this->speaker_task_handle_);
 
-        if (this->speaker_task_handle_ == nullptr) {
-          ESP_LOGE(TAG, "Task failed to start, retrying in 1 second");
-          this->status_momentary_error("task-failure", 1000);
-          this->stop_i2s_driver_();  // Stops the driver to return the lock; will be reloaded in next attempt
-        }
+      if (this->speaker_task_handle_ == nullptr) {
+        ESP_LOGE(TAG, "Task failed to start, retrying in 1 second");
+        this->status_momentary_error("task-failure", 1000);
+        this->stop_i2s_driver_();  // Stops the driver to return the lock; will be reloaded in next attempt
       }
       break;
     case speaker::STATE_RUNNING:   // Intentional fallthrough
@@ -218,8 +221,8 @@ size_t I2SAudioSpeakerBase::play(const uint8_t *data, size_t length, TickType_t
 }
 
 bool I2SAudioSpeakerBase::has_buffered_data() const {
-  if (this->audio_ring_buffer_.use_count() > 0) {
-    std::shared_ptr<ring_buffer::RingBuffer> temp_ring_buffer = this->audio_ring_buffer_.lock();
+  std::shared_ptr<ring_buffer::RingBuffer> temp_ring_buffer = this->audio_ring_buffer_.lock();
+  if (temp_ring_buffer != nullptr) {
     return temp_ring_buffer->available() > 0;
   }
   return false;

esphome/components/logger/logger_esp32.cpp

@@ -3,6 +3,7 @@
 
 #include "esphome/components/esp32/crash_handler.h"
 #include <esp_log.h>
+#include <esp_idf_version.h>
 
 #include <driver/uart.h>
 #include <soc/soc_caps.h>
@@ -16,8 +17,10 @@
 #include <driver/usb_serial_jtag_vfs.h>
 #endif
 #endif
-
-#include "esp_idf_version.h"
+#if defined(CONFIG_PM_ENABLE) && defined(CONFIG_FREERTOS_USE_TICKLESS_IDLE) && \
+    (ESP_IDF_VERSION >= ESP_IDF_VERSION_VAL(6, 0, 0))
+#include "esp_sleep.h"
+#endif
 #include "freertos/FreeRTOS.h"
 
 #include <fcntl.h>
@@ -87,6 +90,12 @@ void init_uart(uart_port_t uart_num, uint32_t baud_rate, int tx_buffer_size) {
   // ESP-IDF requires rx_buffer_size > UART_HW_FIFO_LEN (128 bytes).
   const int min_rx_buffer_size = UART_HW_FIFO_LEN(uart_num) + 1;
   uart_driver_install(uart_num, min_rx_buffer_size, tx_buffer_size, 0, nullptr, 0);
+#if defined(CONFIG_PM_ENABLE) && defined(CONFIG_FREERTOS_USE_TICKLESS_IDLE) && \
+    (ESP_IDF_VERSION >= ESP_IDF_VERSION_VAL(6, 0, 0))
+  // Always flush before going to light sleep. Could be disabled for devices
+  // without TOP_PD or if source_clk = UART_SCLK_RTC
+  esp_sleep_set_console_uart_handling_mode(ESP_SLEEP_ALWAYS_FLUSH_UART);
+#endif
 }
 
 void Logger::pre_setup() {

esphome/components/micro_wake_word/micro_wake_word.cpp

@@ -129,7 +129,7 @@ void MicroWakeWord::setup() {
       return;
     }
     std::shared_ptr<ring_buffer::RingBuffer> temp_ring_buffer = this->ring_buffer_.lock();
-    if (this->ring_buffer_.use_count() > 1) {
+    if (temp_ring_buffer != nullptr) {
       // Producer-only write: never touches consumer state. If the buffer is full, ask the inference task
       // to drain it - reset() is a consumer operation and must run on the inference task's thread.
       // Disable partial writes so audio chunks are either fully accepted or rejected and handled below.
@@ -446,9 +446,9 @@ void MicroWakeWord::loop() {
     xEventGroupClearBits(this->event_group_, EventGroupBits::TASK_STOPPING);
   }
 
-  if ((event_group_bits & EventGroupBits::TASK_STOPPED)) {
+  // Retries on a subsequent loop if the task is still running on the other core
+  if ((event_group_bits & EventGroupBits::TASK_STOPPED) && this->inference_task_.deallocate()) {
     ESP_LOGD(TAG, "Inference task is finished, freeing task resources");
-    this->inference_task_.deallocate();
     xEventGroupClearBits(this->event_group_, ALL_BITS);
     xQueueReset(this->detection_queue_);
     this->set_state_(State::STOPPED);

esphome/components/microphone/microphone_source.h

@@ -48,7 +48,7 @@ class MicrophoneSource final {
   template<typename F> void add_data_callback(F &&data_callback) {
     this->mic_->add_data_callback([this, data_callback](const std::vector<uint8_t> &data) {
       if (this->enabled_ || this->passive_) {
-        if (this->processed_samples_.use_count() == 0) {
+        if (this->processed_samples_ == nullptr) {
           // Create vector if its unused
           this->processed_samples_ = std::make_shared<std::vector<uint8_t>>();
         }

esphome/components/mixer/speaker/mixer_speaker.cpp

@@ -218,7 +218,7 @@ size_t SourceSpeaker::play(const uint8_t *data, size_t length, TickType_t ticks_
   }
   size_t bytes_written = 0;
   std::shared_ptr<ring_buffer::RingBuffer> temp_ring_buffer = this->ring_buffer_.lock();
-  if (temp_ring_buffer.use_count() > 0) {
+  if (temp_ring_buffer != nullptr) {
     // Only write to the ring buffer if the reference is valid
     bytes_written = temp_ring_buffer->write_without_replacement(data, length, ticks_to_wait);
     if (bytes_written > 0) {
@@ -250,14 +250,14 @@ esp_err_t SourceSpeaker::start_() {
   // avoids unnecessary single-frame splices.
   const size_t ring_buffer_size =
       (this->audio_stream_info_.ms_to_bytes(this->buffer_duration_ms_) / bytes_per_frame) * bytes_per_frame;
-  if (this->audio_source_.use_count() == 0) {
+  if (this->audio_source_ == nullptr) {
     std::shared_ptr<ring_buffer::RingBuffer> temp_ring_buffer = this->ring_buffer_.lock();
-    if (!temp_ring_buffer) {
+    if (temp_ring_buffer == nullptr) {
       temp_ring_buffer = ring_buffer::RingBuffer::create(ring_buffer_size);
       this->ring_buffer_ = temp_ring_buffer;
     }
 
-    if (!temp_ring_buffer) {
+    if (temp_ring_buffer == nullptr) {
       return ESP_ERR_NO_MEM;
     }
 
@@ -278,7 +278,7 @@ void SourceSpeaker::stop() { this->send_command_(SOURCE_SPEAKER_COMMAND_STOP); }
 void SourceSpeaker::finish() { this->send_command_(SOURCE_SPEAKER_COMMAND_FINISH); }
 
 bool SourceSpeaker::has_buffered_data() const {
-  return ((this->audio_source_.use_count() > 0) && this->audio_source_->has_buffered_data());
+  return ((this->audio_source_ != nullptr) && this->audio_source_->has_buffered_data());
 }
 
 void SourceSpeaker::set_mute_state(bool mute_state) {
@@ -382,8 +382,8 @@ void MixerSpeaker::loop() {
     ESP_LOGV(TAG, "Stopping");
     xEventGroupClearBits(this->event_group_, MIXER_TASK_STATE_STOPPING);
   }
-  if (event_group_bits & MIXER_TASK_STATE_STOPPED) {
-    this->task_.deallocate();
+  // Retries on a subsequent loop if the task is still running on the other core
+  if ((event_group_bits & MIXER_TASK_STATE_STOPPED) && this->task_.deallocate()) {
     ESP_LOGD(TAG, "Stopped");
     xEventGroupClearBits(this->event_group_, MIXER_TASK_ALL_BITS);
     this->all_stopped_since_ms_ = 0;
@@ -496,7 +496,7 @@ void MixerSpeaker::audio_mixer_task(void *params) {
         if (speaker->is_running() && !speaker->get_pause_state()) {
           // Speaker is running and not paused, so it possibly can provide audio data
           std::shared_ptr<audio::RingBufferAudioSource> audio_source = speaker->get_audio_source().lock();
-          if (audio_source.use_count() == 0) {
+          if (audio_source == nullptr) {
             // No audio source allocated, so skip processing this speaker
             continue;
           }

esphome/components/mlx90614/mlx90614.cpp

@@ -26,44 +26,129 @@ static const uint8_t MLX90614_ID4 = 0x3F;
 
 static const char *const TAG = "mlx90614";
 
+// The EEPROM cell has a limited number of write cycles, so stop retrying after a few failures
+static constexpr uint8_t EMISSIVITY_WRITE_ATTEMPTS = 3;
+
+// SMBus packet error code: CRC-8 with polynomial 0x07, MSB first
+static uint8_t crc8_pec(const uint8_t *data, uint8_t len) { return crc8(data, len, 0x00, 0x07, true); }
+
 void MLX90614Component::setup() {
-  if (!this->write_emissivity_()) {
-    ESP_LOGE(TAG, ESP_LOG_MSG_COMM_FAIL);
-    this->mark_failed();
+  if (std::isnan(this->emissivity_)) {
     return;
   }
+  this->emissivity_write_attempts_ = EMISSIVITY_WRITE_ATTEMPTS;
+  this->try_write_emissivity_();
+  if (this->emissivity_write_attempts_ != 0) {
+    this->status_set_warning(LOG_STR("Failed to write emissivity, will retry"));
+  }
+}
+
+void MLX90614Component::try_write_emissivity_() {
+  if (this->emissivity_write_attempts_ == 0) {
+    return;
+  }
+  if (this->write_emissivity_()) {
+    this->emissivity_write_attempts_ = 0;
+    return;
+  }
+  if (--this->emissivity_write_attempts_ == 0) {
+    ESP_LOGE(TAG, "Giving up on writing emissivity after %u attempts", EMISSIVITY_WRITE_ATTEMPTS);
+    this->emissivity_write_failed_ = true;
+  }
 }
 
 bool MLX90614Component::write_emissivity_() {
-  if (std::isnan(this->emissivity_))
+  // Skip the write when the EEPROM already holds the desired value to save write cycles
+  uint16_t current_emissivity;
+  if (this->read_register_(MLX90614_EMISSIVITY, current_emissivity) != i2c::ERROR_OK) {
+    return false;
+  }
+
+  const auto desired_emissivity = static_cast<uint16_t>(this->emissivity_ * 0xFFFF);
+  if (current_emissivity == desired_emissivity) {
     return true;
-  uint16_t value = (uint16_t) (this->emissivity_ * 65535);
-  if (!this->write_bytes_(MLX90614_EMISSIVITY, 0)) {
-    return false;
   }
-  delay(10);
-  if (!this->write_bytes_(MLX90614_EMISSIVITY, value)) {
-    return false;
-  }
-  delay(10);
-  return true;
+
+  return this->write_register_(MLX90614_EMISSIVITY, desired_emissivity);
 }
 
-bool MLX90614Component::write_bytes_(uint8_t reg, uint16_t data) {
+bool MLX90614Component::write_register_(uint8_t reg, uint16_t data) {
+  // The PEC covers the whole write transaction: SLA+W, command, data low, data high
   uint8_t buf[5];
   buf[0] = this->address_ << 1;
   buf[1] = reg;
-  buf[2] = data & 0xFF;
-  buf[3] = data >> 8;
-  buf[4] = crc8(buf, 4, 0x00, 0x07, true);
-  return this->write_bytes(reg, buf + 2, 3);
+
+  // See datasheet 8.3.3.1 EEPROM write sequence
+  // 1. Write 0x0000 into the cell of interest (erases the cell)
+  buf[2] = buf[3] = 0;
+  buf[4] = crc8_pec(buf, 4);
+  auto ec = this->write_register(reg, buf + 2, 3);
+  if (ec != i2c::ERROR_OK) {
+    ESP_LOGW(TAG, "Can't erase register 0x%02X, error %d", reg, ec);
+    return false;
+  }
+
+  // 2. Wait at least 5ms
+  delay(10);
+
+  // 3. Write the new value
+  if (data != 0) {
+    buf[2] = data & 0xFF;
+    buf[3] = data >> 8;
+    buf[4] = crc8_pec(buf, 4);
+    ec = this->write_register(reg, buf + 2, 3);
+    if (ec != i2c::ERROR_OK) {
+      ESP_LOGW(TAG, "Can't write register 0x%02X, error %d", reg, ec);
+      return false;
+    }
+    // 4. Wait at least 5ms
+    delay(10);
+  }
+
+  // 5. Read back to confirm the value was stored
+  uint16_t read_back;
+  ec = this->read_register_(reg, read_back);
+  if (ec != i2c::ERROR_OK) {
+    ESP_LOGW(TAG, "Can't check register 0x%02X value, error %d", reg, ec);
+    return false;
+  }
+
+  if (read_back != data) {
+    ESP_LOGW(TAG, "Read back mismatch on register 0x%02X. Expected 0x%04X, got 0x%04X", reg, data, read_back);
+    return false;
+  }
+
+  return true;
+}
+
+i2c::ErrorCode MLX90614Component::read_register_(uint8_t reg, uint16_t &data) {
+  // The PEC covers the whole read transaction: SLA+W, command, SLA+R, data low, data high
+  uint8_t buf[6];
+  buf[0] = this->address_ << 1;
+  buf[1] = reg;
+  buf[2] = (this->address_ << 1) | 0x01;
+
+  const auto ec = this->read_register(reg, buf + 3, 3);
+  if (ec != i2c::ERROR_OK) {
+    ESP_LOGW(TAG, "i2c read error %d", ec);
+    return ec;
+  }
+
+  const auto expected_pec = crc8_pec(buf, 5);
+  if (buf[5] != expected_pec) {
+    ESP_LOGW(TAG, "i2c CRC error. Expected 0x%02X, got 0x%02X", expected_pec, buf[5]);
+    return i2c::ERROR_CRC;
+  }
+
+  data = encode_uint16(buf[4], buf[3]);
+  return i2c::ERROR_OK;
 }
 
 void MLX90614Component::dump_config() {
   ESP_LOGCONFIG(TAG, "MLX90614:");
   LOG_I2C_DEVICE(this);
-  if (this->is_failed()) {
-    ESP_LOGE(TAG, ESP_LOG_MSG_COMM_FAIL);
+  if (this->emissivity_write_attempts_ != 0) {
+    ESP_LOGW(TAG, "  Emissivity not written yet, will retry");
   }
   LOG_UPDATE_INTERVAL(this);
   LOG_SENSOR("  ", "Ambient", this->ambient_sensor_);
@@ -71,33 +156,41 @@ void MLX90614Component::dump_config() {
 }
 
 void MLX90614Component::update() {
-  uint8_t emissivity[3];
-  if (this->read_register(MLX90614_EMISSIVITY, emissivity, 3) != i2c::ERROR_OK) {
-    this->status_set_warning();
-    return;
+  // Temperature reads run regardless of the emissivity state so a failure still shows up as NAN
+  this->try_write_emissivity_();
+
+  // Publishes NAN on a bus or CRC failure so a stuck reading is visible instead of silently stale
+  auto publish_sensor = [this](sensor::Sensor *sensor, uint8_t reg) {
+    if (sensor == nullptr) {
+      return i2c::ERROR_OK;
+    }
+
+    uint16_t raw;
+    const auto ec = this->read_register_(reg, raw);
+    if (ec != i2c::ERROR_OK) {
+      sensor->publish_state(NAN);
+      return ec;
+    }
+
+    // Bit 15 set means the device flagged the reading as invalid
+    const float temperature = (raw & 0x8000) ? NAN : raw * 0.02f - 273.15f;
+    ESP_LOGD(TAG, "'%s': Got temperature=%.1f°C", sensor->get_name().c_str(), temperature);
+    sensor->publish_state(temperature);
+    return ec;
+  };
+
+  const auto object_ec = publish_sensor(this->object_sensor_, MLX90614_TEMPERATURE_OBJECT_1);
+  const auto ambient_ec = publish_sensor(this->ambient_sensor_, MLX90614_TEMPERATURE_AMBIENT);
+
+  if (object_ec != i2c::ERROR_OK || ambient_ec != i2c::ERROR_OK) {
+    this->status_set_warning(LOG_STR("Failed to read some sensors"));
+  } else if (this->emissivity_write_failed_) {
+    this->status_set_warning(LOG_STR("Failed to write emissivity"));
+  } else if (this->emissivity_write_attempts_ != 0) {
+    this->status_set_warning(LOG_STR("Failed to write emissivity, will retry"));
+  } else {
+    this->status_clear_warning();
   }
-  uint8_t raw_object[3];
-  if (this->read_register(MLX90614_TEMPERATURE_OBJECT_1, raw_object, 3) != i2c::ERROR_OK) {
-    this->status_set_warning();
-    return;
-  }
-
-  uint8_t raw_ambient[3];
-  if (this->read_register(MLX90614_TEMPERATURE_AMBIENT, raw_ambient, 3) != i2c::ERROR_OK) {
-    this->status_set_warning();
-    return;
-  }
-
-  float ambient = raw_ambient[1] & 0x80 ? NAN : encode_uint16(raw_ambient[1], raw_ambient[0]) * 0.02f - 273.15f;
-  float object = raw_object[1] & 0x80 ? NAN : encode_uint16(raw_object[1], raw_object[0]) * 0.02f - 273.15f;
-
-  ESP_LOGD(TAG, "Got Temperature=%.1f°C Ambient=%.1f°C", object, ambient);
-
-  if (this->ambient_sensor_ != nullptr && !std::isnan(ambient))
-    this->ambient_sensor_->publish_state(ambient);
-  if (this->object_sensor_ != nullptr && !std::isnan(object))
-    this->object_sensor_->publish_state(object);
-  this->status_clear_warning();
 }
 
 }  // namespace esphome::mlx90614

esphome/components/mlx90614/mlx90614.h

@@ -18,13 +18,18 @@ class MLX90614Component final : public PollingComponent, public i2c::I2CDevice {
   void set_emissivity(float emissivity) { emissivity_ = emissivity; }
 
  protected:
+  void try_write_emissivity_();
   bool write_emissivity_();
 
-  bool write_bytes_(uint8_t reg, uint16_t data);
+  bool write_register_(uint8_t reg, uint16_t data);
+  i2c::ErrorCode read_register_(uint8_t reg, uint16_t &data);
 
   sensor::Sensor *ambient_sensor_{nullptr};
   sensor::Sensor *object_sensor_{nullptr};
 
   float emissivity_{NAN};
+  // Remaining attempts to program the emissivity EEPROM cell, bounded to limit cell wear
+  uint8_t emissivity_write_attempts_{0};
+  bool emissivity_write_failed_{false};
 };
 }  // namespace esphome::mlx90614

esphome/components/network/util.h

@@ -26,30 +26,34 @@ namespace esphome::network {
 
 /// Return whether the node is connected to the network (through wifi, eth, ...)
 ESPHOME_ALWAYS_INLINE inline bool is_connected() {
+  // With a single interface enabled the checks below collapse to `if (x) return true; return false;`, which
+  // clang-tidy wants folded into one return. Keep the per-interface form so every enabled interface is checked.
+  // NOLINTBEGIN(readability-simplify-boolean-expr)
 #ifdef USE_ETHERNET
   if (ethernet::global_eth_component != nullptr && ethernet::global_eth_component->is_connected())
     return true;
 #endif
 
 #ifdef USE_MODEM
-  if (modem::global_modem_component != nullptr)
-    return modem::global_modem_component->is_connected();
+  if (modem::global_modem_component != nullptr && modem::global_modem_component->is_connected())
+    return true;
 #endif
 
 #ifdef USE_WIFI
-  if (wifi::global_wifi_component != nullptr)
-    return wifi::global_wifi_component->is_connected();
+  if (wifi::global_wifi_component != nullptr && wifi::global_wifi_component->is_connected())
+    return true;
 #endif
 
 #ifdef USE_OPENTHREAD
-  if (openthread::global_openthread_component != nullptr)
-    return openthread::global_openthread_component->is_connected();
+  if (openthread::global_openthread_component != nullptr && openthread::global_openthread_component->is_connected())
+    return true;
 #endif
 
 #ifdef USE_HOST
   return true;  // Assume it's connected
 #endif
   return false;
+  // NOLINTEND(readability-simplify-boolean-expr)
 }
 
 /// Return whether the network is disabled: every configured interface with a

esphome/components/noise/__init__.py

@@ -88,12 +88,12 @@ def encryption_schema(config: ConfigType | None) -> ConfigType:
 
 async def to_code(config: ConfigType) -> None:
     cg.add_define("USE_NOISE")
-    cg.add_library("esphome/noise-c", "0.1.24")
+    cg.add_library("esphome/noise-c", "0.1.26")
     # noise-c depends on libsodium, but declaring it here too lets the
     # library manager see the full set up front instead of discovering
     # libsodium only after noise-c has downloaded, so the two can download
     # in parallel. The version must match noise-c's library.json.
-    cg.add_library("esphome/libsodium", "1.10021.6")
+    cg.add_library("esphome/libsodium", "1.10021.8")
     # Enable optimized memzero/memcmp in libsodium instead of volatile byte loops
     cg.add_build_flag("-DHAVE_WEAK_SYMBOLS=1")
     cg.add_build_flag("-DHAVE_INLINE_ASM=1")

esphome/components/resampler/speaker/resampler_speaker.cpp

@@ -153,8 +153,8 @@ void ResamplerSpeaker::loop() {
     ESP_LOGV(TAG, "Stopping");
     xEventGroupClearBits(this->event_group_, ResamplingEventGroupBits::STATE_STOPPING);
   }
-  if (event_group_bits & ResamplingEventGroupBits::STATE_STOPPED) {
-    this->task_.deallocate();
+  // Retries on a subsequent loop if the task is still running on the other core
+  if ((event_group_bits & ResamplingEventGroupBits::STATE_STOPPED) && this->task_.deallocate()) {
     ESP_LOGD(TAG, "Stopped");
     xEventGroupClearBits(this->event_group_, ResamplingEventGroupBits::ALL_BITS);
   }
@@ -235,7 +235,7 @@ size_t ResamplerSpeaker::play(const uint8_t *data, size_t length, TickType_t tic
     bytes_written = this->output_speaker_->play(data, length, ticks_to_wait);
   } else {
     std::shared_ptr<ring_buffer::RingBuffer> temp_ring_buffer = this->ring_buffer_.lock();
-    if (temp_ring_buffer) {
+    if (temp_ring_buffer != nullptr) {
       // Only write to the ring buffer if the reference is valid
       bytes_written = temp_ring_buffer->write_without_replacement(data, length, ticks_to_wait);
     } else {
@@ -299,7 +299,7 @@ bool ResamplerSpeaker::has_buffered_data() const {
   bool has_ring_buffer_data = false;
   if (this->requires_resampling_()) {
     std::shared_ptr<ring_buffer::RingBuffer> temp_ring_buffer = this->ring_buffer_.lock();
-    if (temp_ring_buffer) {
+    if (temp_ring_buffer != nullptr) {
       has_ring_buffer_data = (temp_ring_buffer->available() > 0);
     }
   }
@@ -342,7 +342,7 @@ void ResamplerSpeaker::resample_task(void *params) {
       std::shared_ptr<ring_buffer::RingBuffer> temp_ring_buffer = ring_buffer::RingBuffer::create(
           this_resampler->audio_stream_info_.ms_to_bytes(this_resampler->buffer_duration_ms_));
 
-      if (!temp_ring_buffer) {
+      if (temp_ring_buffer == nullptr) {
         err = ESP_ERR_NO_MEM;
       } else {
         this_resampler->ring_buffer_ = temp_ring_buffer;

esphome/components/sendspin/__init__.py

@@ -6,12 +6,17 @@ from esphome.components import esp32, network, psram, socket, wifi
 import esphome.config_validation as cv
 from esphome.const import (
     CONF_BUFFER_SIZE,
+    CONF_ESPHOME,
     CONF_FORMAT,
     CONF_HEIGHT,
     CONF_ID,
+    CONF_MODEL,
+    CONF_NAME,
+    CONF_PROJECT,
     CONF_SAMPLE_RATE,
     CONF_SOURCE,
     CONF_TASK_STACK_IN_PSRAM,
+    CONF_VERSION,
     CONF_WIDTH,
 )
 from esphome.core import CORE, ID
@@ -27,9 +32,18 @@ DOMAIN = "sendspin"
 CONF_DISPLAY_OFFSET = "display_offset"
 CONF_SENDSPIN_ID = "sendspin_id"
 
+CONF_FIRMWARE_VERSION = "firmware_version"
+CONF_MANUFACTURER = "manufacturer"
+
+# An empty device information string would be sent to the server as an empty value rather than
+# falling back, so reject it instead of silently substituting the fallback. The 127 byte cap keeps
+# the length prefix of a protobuf string field to a single byte, matching `esphome: project:`.
+DEVICE_INFO_STRING = cv.All(cv.string_strict, cv.Length(min=1), cv.ByteLength(max=127))
+
 CONF_INITIAL_STATIC_DELAY = "initial_static_delay"
 CONF_FIXED_DELAY = "fixed_delay"
 CONF_DECODE_MEMORY = "decode_memory"
+CONF_CODECS = "codecs"
 
 # Matches ARTWORK_MAX_SLOTS in sendspin-cpp.
 MAX_ARTWORK_SLOTS = 4
@@ -44,6 +58,20 @@ CODEC_FORMAT_OPUS = SendspinCodecFormat.enum("OPUS")
 CODEC_FORMAT_PCM = SendspinCodecFormat.enum("PCM")
 CODEC_FORMAT_UNSUPPORTED = SendspinCodecFormat.enum("UNSUPPORTED")
 
+CODEC_FLAC = "flac"
+CODEC_OPUS = "opus"
+CODEC_PCM = "pcm"
+
+CODECS = {
+    CODEC_FLAC: CODEC_FORMAT_FLAC,
+    CODEC_OPUS: CODEC_FORMAT_OPUS,
+    CODEC_PCM: CODEC_FORMAT_PCM,
+}
+
+# Opus only supports 48 kHz audio, so it is left out of the default list at other rates.
+DEFAULT_CODECS = [CODEC_FLAC, CODEC_OPUS, CODEC_PCM]
+OPUS_SAMPLE_RATE = 48000
+
 SendspinImageFormat = sendspin_library_ns.enum("SendspinImageFormat", is_class=True)
 IMAGE_FORMAT_JPEG = SendspinImageFormat.enum("JPEG")
 IMAGE_FORMAT_PNG = SendspinImageFormat.enum("PNG")
@@ -183,6 +211,9 @@ CONFIG_SCHEMA = cv.All(
         {
             cv.GenerateID(): cv.declare_id(SendspinHub),
             cv.Optional(CONF_TASK_STACK_IN_PSRAM): psram.validate_task_stack_in_psram,
+            cv.Optional(CONF_MANUFACTURER): DEVICE_INFO_STRING,
+            cv.Optional(CONF_MODEL): DEVICE_INFO_STRING,
+            cv.Optional(CONF_FIRMWARE_VERSION): DEVICE_INFO_STRING,
         }
     ),
     cv.only_on_esp32,
@@ -233,6 +264,22 @@ async def to_code(config: ConfigType) -> None:
         cg.add(var.set_task_stack_in_psram(True))
         psram.request_external_task_stack()
 
+    # Device information for the server's client/hello message. Falls back to the project
+    # information, which is written as `manufacturer.model`. Anything still unset keeps the
+    # default the hub itself applies: the ESPHome name and version.
+    project = CORE.config[CONF_ESPHOME].get(CONF_PROJECT, {})
+    project_manufacturer, _, project_model = project.get(CONF_NAME, "").partition(".")
+    for value, setter in (
+        (config.get(CONF_MANUFACTURER) or project_manufacturer, var.set_manufacturer),
+        (config.get(CONF_MODEL) or project_model, var.set_model),
+        (
+            config.get(CONF_FIRMWARE_VERSION) or project.get(CONF_VERSION),
+            var.set_firmware_version,
+        ),
+    ):
+        if value:
+            cg.add(setter(value))
+
     # sendspin-cpp library
     esp32.add_idf_component(name="sendspin/sendspin-cpp", ref="0.7.2")
 
@@ -286,16 +333,13 @@ async def to_code(config: ConfigType) -> None:
     if data.player_support:
         cg.add_define("USE_SENDSPIN_PLAYER", True)
 
-        # Configures the player role. We always assume support for 16 bits per sample mono and stereo FLAC, Opus, and PCM at the configured sample rate
-        # (with Opus only supported at 48 kHz since that's the only sample rate it supports). Users can configure the specific formats via the Sendspin server
+        # Configures the player role. Each configured codec is advertised for 16 bits per sample
+        # mono and stereo at the configured sample rate. The order is a preference order, both for
+        # the codecs themselves and for stereo over mono.
         player_cfg = data.player_config
         sample_rate = player_cfg[CONF_SAMPLE_RATE]
 
-        # OPUS only supports 48 kHz audio
-        codecs = [CODEC_FORMAT_FLAC]
-        if sample_rate == 48000:
-            codecs.append(CODEC_FORMAT_OPUS)
-        codecs.append(CODEC_FORMAT_PCM)
+        codecs = [CODECS[codec] for codec in player_cfg[CONF_CODECS]]
 
         def _audio_format(codec: MockObj, channels: int) -> cg.StructInitializer:
             return cg.StructInitializer(

esphome/components/sendspin/media_source/__init__.py

@@ -13,11 +13,16 @@ from esphome.cpp_generator import MockObj, TemplateArgsType
 from esphome.types import ConfigType
 
 from .. import (
+    CODEC_OPUS,
+    CODECS,
+    CONF_CODECS,
     CONF_DECODE_MEMORY,
     CONF_FIXED_DELAY,
     CONF_INITIAL_STATIC_DELAY,
     CONF_SENDSPIN_ID,
+    DEFAULT_CODECS,
     MEMORY_LOCATIONS,
+    OPUS_SAMPLE_RATE,
     SendspinHub,
     register_player_config,
     request_controller_support,
@@ -49,10 +54,32 @@ DisableStaticDelayAdjustmentAction = sendspin_ns.class_(
 )
 
 
+def _resolve_codecs(config: ConfigType) -> ConfigType:
+    """Validate the codec preference list, filling in the default when it is not set."""
+    sample_rate = config[CONF_SAMPLE_RATE]
+    if (codecs := config.get(CONF_CODECS)) is None:
+        config[CONF_CODECS] = [
+            codec
+            for codec in DEFAULT_CODECS
+            if codec != CODEC_OPUS or sample_rate == OPUS_SAMPLE_RATE
+        ]
+        return config
+
+    if len(set(codecs)) != len(codecs):
+        raise cv.Invalid("Each codec may only be listed once", path=[CONF_CODECS])
+    if CODEC_OPUS in codecs and sample_rate != OPUS_SAMPLE_RATE:
+        raise cv.Invalid(
+            f"Codec '{CODEC_OPUS}' requires a {CONF_SAMPLE_RATE} of {OPUS_SAMPLE_RATE}",
+            path=[CONF_CODECS],
+        )
+    return config
+
+
 def _register(config: ConfigType) -> ConfigType:
     request_controller_support()
     register_player_config(
         {
+            CONF_CODECS: config[CONF_CODECS],
             CONF_SAMPLE_RATE: config[CONF_SAMPLE_RATE],
             CONF_BUFFER_SIZE: config[CONF_BUFFER_SIZE],
             CONF_INITIAL_STATIC_DELAY: config[CONF_INITIAL_STATIC_DELAY],
@@ -85,9 +112,13 @@ CONFIG_SCHEMA = cv.All(
                 min=16000, max=96000
             ),
             cv.Optional(CONF_DECODE_MEMORY): cv.one_of(*MEMORY_LOCATIONS, lower=True),
+            cv.Optional(CONF_CODECS): cv.All(
+                cv.ensure_list(cv.enum(CODECS, lower=True)), cv.Length(min=1)
+            ),
         }
     ),
     cv.only_on_esp32,
+    _resolve_codecs,
     _register,
 )
 

esphome/components/sendspin/sendspin_hub.cpp

@@ -76,8 +76,12 @@ void SendspinHub::dump_config() {
   ESP_LOGCONFIG(TAG,
                 "Sendspin Hub:\n"
                 "  Client ID: %s\n"
+                "  Manufacturer: %s\n"
+                "  Model: %s\n"
+                "  Firmware version: %s\n"
                 "  Task stack in PSRAM: %s",
-                get_client_id_into_buffer(mac_buf), YESNO(this->task_stack_in_psram_));
+                get_client_id_into_buffer(mac_buf), this->manufacturer_, this->get_product_name_(),
+                this->firmware_version_, YESNO(this->task_stack_in_psram_));
 
 #ifdef USE_SENDSPIN_ARTWORK
   // Slot indices come from the order the image platform entries were declared, so the log is the
@@ -127,15 +131,19 @@ const char *SendspinHub::get_client_id_into_buffer(std::span<char, MAC_ADDRESS_P
   return get_mac_address_pretty_into_buffer(buf);
 }
 
+const char *SendspinHub::get_product_name_() const {
+  return this->model_ != nullptr ? this->model_ : App.get_name().c_str();
+}
+
 sendspin::SendspinClientConfig SendspinHub::build_client_config_() {
   sendspin::SendspinClientConfig config;
 
   char mac_buf[MAC_ADDRESS_PRETTY_BUFFER_SIZE];
   config.client_id = SendspinHub::get_client_id_into_buffer(mac_buf);
   config.name = App.get_friendly_name();
-  config.product_name = App.get_name();
-  config.manufacturer = "ESPHome";
-  config.software_version = ESPHOME_VERSION;
+  config.product_name = this->get_product_name_();
+  config.manufacturer = this->manufacturer_;
+  config.software_version = this->firmware_version_;
   config.httpd_psram_stack = this->task_stack_in_psram_;
 
   return config;

esphome/components/sendspin/sendspin_hub.h

@@ -8,6 +8,7 @@
 #include "esphome/core/component.h"
 #include "esphome/core/helpers.h"
 #include "esphome/core/preferences.h"
+#include "esphome/core/version.h"
 
 #include <sendspin/client.h>
 #include <sendspin/config.h>
@@ -125,6 +126,15 @@ class SendspinHub final : public Component,
 
   void set_task_stack_in_psram(bool task_stack_in_psram) { this->task_stack_in_psram_ = task_stack_in_psram; }
 
+  /// @brief Sets the device information reported to the server in the `client/hello` message.
+  ///
+  /// Each takes a pointer to a string literal emitted by codegen, so it must stay valid for the
+  /// lifetime of the hub. Only called for values the configuration overrides; anything left alone
+  /// keeps the default described on the member below.
+  void set_manufacturer(const char *manufacturer) { this->manufacturer_ = manufacturer; }
+  void set_model(const char *model) { this->model_ = model; }
+  void set_firmware_version(const char *firmware_version) { this->firmware_version_ = firmware_version; }
+
   // --- Sendspin role specific methods ---
 
 #ifdef USE_SENDSPIN_ARTWORK
@@ -187,6 +197,9 @@ class SendspinHub final : public Component,
   /// @brief Builds the SendspinClientConfig from ESPHome configuration and platform info.
   sendspin::SendspinClientConfig build_client_config_();
 
+  /// @brief Returns the product name reported to the server: the configured model, or the device name.
+  const char *get_product_name_() const;
+
   /// @brief Writes the active network interface's MAC into @p buf and returns its data pointer.
   /// Uses the ethernet MAC if ethernet is configured, otherwise the base MAC (used by wifi).
   static const char *get_client_id_into_buffer(std::span<char, MAC_ADDRESS_PRETTY_BUFFER_SIZE> buf);
@@ -268,6 +281,12 @@ class SendspinHub final : public Component,
   CallbackManager<void(const sendspin::GroupUpdateObject &)> group_update_callbacks_{};
 
   bool task_stack_in_psram_{false};
+
+  // Device information sent in the `client/hello` message. Defaults apply when neither the
+  // sendspin configuration nor the project information supplies a value.
+  const char *manufacturer_{"ESPHome"};
+  const char *model_{nullptr};  // nullptr reports the device name instead
+  const char *firmware_version_{ESPHOME_VERSION};
 };
 
 /// @brief Base class for all sendspin subcomponents.

esphome/components/serial_proxy/__init__.py

@@ -30,6 +30,7 @@ MULTI_CONF = True
 
 serial_proxy_ns = cg.esphome_ns.namespace("serial_proxy")
 SerialProxy = serial_proxy_ns.class_("SerialProxy", cg.Component, uart.UARTDevice)
+SerialProxyTap = serial_proxy_ns.class_("SerialProxyTap")
 
 api_enums_ns = cg.esphome_ns.namespace("api").namespace("enums")
 SerialProxyPortType = api_enums_ns.enum("SerialProxyPortType")

esphome/components/serial_proxy/serial_proxy.cpp

@@ -29,26 +29,57 @@ void SerialProxy::setup() {
 #ifdef USE_API
   // instance_index_ is fixed at registration time; pre-set it so loop() only needs to update data
   this->outgoing_msg_.instance = this->instance_index_;
+#endif
+#ifdef USE_SERIAL_PROXY_TAP
+  // A tap sets itself up before this runs (its setup priority is higher), so it may
+  // already be waiting on the port -- a boot-time handshake with the device, say. Leaving
+  // the loop enabled is what lets that finish; without it the tap would stall until a
+  // client happened to subscribe.
+  if (this->tap_ != nullptr && this->tap_->tap_needs_port()) {
+    return;
+  }
 #endif
   // No subscriber at startup; disable loop until a client subscribes
   this->disable_loop();
 }
 
-void SerialProxy::loop() {
-#ifdef USE_API
-  // Safety check — loop should only run when subscribed, but guard against races
-  if (this->api_connection_ == nullptr) [[unlikely]] {
-    this->disable_loop();
+#ifdef USE_SERIAL_PROXY_TAP
+void SerialProxy::reset_mode_() {
+  // The mode belongs to a session, not to the port. Carrying a departed client's choice
+  // over to the next one would inject protocol bytes into a stream that never asked for
+  // them -- a firmware upload, or any client built before this request existed and so
+  // unable to turn it off. Guessing RAW is the safe direction: a client that wanted
+  // protocol handling and did not ask for it merely sends its own acknowledgements.
+  if (this->mode_ == api::enums::SERIAL_PROXY_MODE_RAW) {
     return;
   }
+  ESP_LOGD(TAG, "Session ended, returning serial proxy [%" PRIu32 "] to RAW mode", this->instance_index_);
+  this->mode_ = api::enums::SERIAL_PROXY_MODE_RAW;
+}
+#endif
 
+void SerialProxy::loop() {
+#ifdef USE_API
   // Detect subscriber disconnect
-  if (this->api_connection_->is_marked_for_removal() || !this->api_connection_->is_connection_setup() ||
-      !api_is_connected()) {
+  if (this->api_connection_ != nullptr && (this->api_connection_->is_marked_for_removal() ||
+                                           !this->api_connection_->is_connection_setup() || !api_is_connected())) {
     ESP_LOGW(TAG, "Subscriber disconnected");
     this->api_connection_ = nullptr;
+    this->reset_mode_();
+  }
+
+  // With no subscriber there is normally nothing to do, but a tap may still need the port
+  // read -- it does its protocol work precisely while nobody else is listening.
+  if (this->api_connection_ == nullptr) [[unlikely]] {
+#ifdef USE_SERIAL_PROXY_TAP
+    if (this->tap_ == nullptr || !this->tap_->tap_needs_port()) {
+      this->disable_loop();
+      return;
+    }
+#else
     this->disable_loop();
     return;
+#endif
   }
 
   // Read available data from UART and forward to subscribed client
@@ -69,11 +100,54 @@ void __attribute__((noinline)) SerialProxy::read_and_send_(size_t available) {
   if (!this->read_array(buffer, to_read))
     return;
 
+#ifdef USE_SERIAL_PROXY_TAP
+  // Before forwarding, so a tap that answers the device (an acknowledgement, say) is not
+  // waiting on the network round trip to a subscriber that may not even exist.
+  if (this->tap_observing_()) {
+    this->tap_->on_device_rx(buffer, to_read);
+  }
+#endif
+
+  if (this->api_connection_ == nullptr) {
+    return;
+  }
   this->outgoing_msg_.set_data(buffer, to_read);
   this->api_connection_->send_serial_proxy_data(this->outgoing_msg_);
 }
 #endif
 
+#ifdef USE_SERIAL_PROXY_TAP
+
+bool SerialProxy::tap_observing_() const {
+  if (this->tap_ == nullptr) {
+    return false;
+  }
+  // With no subscriber, a tap doing its own protocol work (the boot-time handshake with
+  // the device, say) is served regardless of mode -- nobody has chosen one yet. Once a
+  // subscriber holds the port, the mode alone decides, so RAW stays inert.
+  if (this->api_connection_ == nullptr && this->tap_->tap_needs_port()) {
+    return true;
+  }
+  // Otherwise the mode decides. RAW must be inert: a client that flips to RAW before
+  // flashing firmware is entitled to a byte pipe with nothing injecting protocol bytes
+  // into it, and "the tap turned out not to recognise the stream" is not good enough.
+  return this->mode_ == api::enums::SERIAL_PROXY_MODE_PROTOCOL;
+}
+
+void SerialProxy::tap_pump() {
+#ifdef USE_API
+  // Nothing would consume the bytes; leave them in the FIFO
+  if (!this->tap_observing_() && this->api_connection_ == nullptr) {
+    return;
+  }
+  const size_t available = this->available();
+  if (available > 0) {
+    this->read_and_send_(available);
+  }
+#endif
+}
+#endif
+
 void SerialProxy::dump_config() {
   ESP_LOGCONFIG(TAG,
                 "Serial Proxy [%" PRIu32 "]:\n"
@@ -92,8 +166,9 @@ void SerialProxy::dump_config() {
 SerialProxyResult SerialProxy::configure(api::APIConnection *api_connection, uint32_t baudrate, bool flow_control,
                                          uint8_t parity, uint8_t stop_bits, uint8_t data_size) {
 #ifdef USE_API
-  if (this->port_claimed_by_other_(api_connection)) {
-    ESP_LOGW(TAG, "Ignoring configure request from client without port access [%" PRIu32 "]", this->instance_index_);
+  if (!this->is_subscriber_(api_connection)) {
+    ESP_LOGW(TAG, "Ignoring configure request from client without port subscription [%" PRIu32 "]",
+             this->instance_index_);
     return SerialProxyResult::SERIAL_PROXY_RESULT_PORT_IN_USE;
   }
 #endif
@@ -159,24 +234,80 @@ SerialProxyResult SerialProxy::configure(api::APIConnection *api_connection, uin
   return SerialProxyResult::SERIAL_PROXY_RESULT_OK;
 }
 
+SerialProxyResult SerialProxy::set_mode_from_client(api::APIConnection *api_connection,
+                                                    api::enums::SerialProxyMode mode) {
+#ifdef USE_API
+  // Only the live subscriber may change the mode, so the mode cannot outlive a session
+  if (!this->is_subscriber_(api_connection)) {
+    ESP_LOGW(TAG, "Ignoring mode request from client without port subscription [%" PRIu32 "]", this->instance_index_);
+    return SerialProxyResult::SERIAL_PROXY_RESULT_PORT_IN_USE;
+  }
+#endif
+  // Values come from a remote client
+  if (mode != api::enums::SERIAL_PROXY_MODE_RAW && mode != api::enums::SERIAL_PROXY_MODE_PROTOCOL) {
+    ESP_LOGW(TAG, "Invalid mode: %" PRIu32, static_cast<uint32_t>(mode));
+    return SerialProxyResult::SERIAL_PROXY_RESULT_INVALID_ARGUMENT;
+  }
+  // PROTOCOL on a port with no tap would be a silent no-op; refuse so the client knows
+#ifdef USE_SERIAL_PROXY_TAP
+  const bool has_tap = this->tap_ != nullptr;
+#else
+  const bool has_tap = false;
+#endif
+  if (mode == api::enums::SERIAL_PROXY_MODE_PROTOCOL && !has_tap) {
+    ESP_LOGW(TAG, "No tap on serial proxy [%" PRIu32 "]; PROTOCOL mode unavailable", this->instance_index_);
+    return SerialProxyResult::SERIAL_PROXY_RESULT_NOT_SUPPORTED;
+  }
+  ESP_LOGD(TAG, "Serial proxy [%" PRIu32 "] mode set to %s", this->instance_index_,
+           mode == api::enums::SERIAL_PROXY_MODE_PROTOCOL ? LOG_STR_LITERAL("PROTOCOL") : LOG_STR_LITERAL("RAW"));
+#ifdef USE_SERIAL_PROXY_TAP
+  const bool leaving_protocol_mode =
+      this->mode_ != api::enums::SERIAL_PROXY_MODE_RAW && mode == api::enums::SERIAL_PROXY_MODE_RAW;
+  this->mode_ = mode;
+
+  // Only for an explicit client request, not for reset_mode_() at the end of a session:
+  // an ordinary disconnect says nothing about the device, whereas a client deliberately
+  // asking for raw bytes usually precedes changing what the device is.
+  if (leaving_protocol_mode && this->tap_ != nullptr) {
+    this->tap_->on_protocol_disabled();
+  }
+#endif
+  return SerialProxyResult::SERIAL_PROXY_RESULT_OK;
+}
+
 void SerialProxy::write_from_client(api::APIConnection *api_connection, const uint8_t *data, size_t len) {
 #ifdef USE_API
-  // Bytes from a client other than the live subscriber would interleave with the
-  // subscriber's traffic on the wire
-  if (this->port_claimed_by_other_(api_connection)) {
-    ESP_LOGW(TAG, "Ignoring write from client without port access [%" PRIu32 "]", this->instance_index_);
+  // Bytes from anyone but the live subscriber would interleave with the subscriber's
+  // traffic -- or with an active tap's -- on the wire
+  if (!this->is_subscriber_(api_connection)) {
+    if (this->api_connection_ != nullptr) {
+      ESP_LOGW(TAG, "Ignoring write from client that does not hold serial proxy [%" PRIu32 "]", this->instance_index_);
+    } else {
+      // A legacy client streaming writes without subscribing would flood WARN, one per
+      // request; writes are the only high-rate, unacknowledged operation, so keep this
+      // visible without drowning the log
+      ESP_LOGV(TAG, "Ignoring write from client without port subscription [%" PRIu32 "]", this->instance_index_);
+    }
     return;
   }
 #endif
   if (data == nullptr || len == 0)
     return;
   this->write_array(data, len);
+
+#ifdef USE_SERIAL_PROXY_TAP
+  // After the write, so the tap observes the same ordering the device does
+  if (this->tap_observing_()) {
+    this->tap_->on_client_tx(data, len);
+  }
+#endif
 }
 
 SerialProxyResult SerialProxy::set_modem_pins(api::APIConnection *api_connection, uint32_t line_states) {
 #ifdef USE_API
-  if (this->port_claimed_by_other_(api_connection)) {
-    ESP_LOGW(TAG, "Ignoring modem pin request from client without port access [%" PRIu32 "]", this->instance_index_);
+  if (!this->is_subscriber_(api_connection)) {
+    ESP_LOGW(TAG, "Ignoring modem pin request from client without port subscription [%" PRIu32 "]",
+             this->instance_index_);
     return SerialProxyResult::SERIAL_PROXY_RESULT_PORT_IN_USE;
   }
 #endif
@@ -210,8 +341,8 @@ uint32_t SerialProxy::get_modem_pins() const {
 SerialProxyResult SerialProxy::flush_port(api::APIConnection *api_connection) {
 #ifdef USE_API
   // Flushing stalls the port, so it gets the same ownership check as writes
-  if (this->port_claimed_by_other_(api_connection)) {
-    ESP_LOGW(TAG, "Ignoring flush from client without port access [%" PRIu32 "]", this->instance_index_);
+  if (!this->is_subscriber_(api_connection)) {
+    ESP_LOGW(TAG, "Ignoring flush from client without port subscription [%" PRIu32 "]", this->instance_index_);
     return SerialProxyResult::SERIAL_PROXY_RESULT_PORT_IN_USE;
   }
 #endif
@@ -230,11 +361,6 @@ SerialProxyResult SerialProxy::flush_port(api::APIConnection *api_connection) {
 }
 
 #ifdef USE_API
-bool SerialProxy::port_claimed_by_other_(api::APIConnection *api_connection) const {
-  return this->api_connection_ != nullptr && this->api_connection_ != api_connection &&
-         this->api_connection_->is_connection_setup();
-}
-
 SerialProxyResult SerialProxy::serial_proxy_request(api::APIConnection *api_connection,
                                                     api::enums::SerialProxyRequestType type) {
   switch (type) {
@@ -252,6 +378,10 @@ SerialProxyResult SerialProxy::serial_proxy_request(api::APIConnection *api_conn
           return SerialProxyResult::SERIAL_PROXY_RESULT_PORT_IN_USE;
         }
         ESP_LOGW(TAG, "Previous subscriber disconnected; taking over subscription");
+        // End the dead client's session before starting the new one, so its mode
+        // cannot leak into a session that never asked for it
+        this->api_connection_ = nullptr;
+        this->reset_mode_();
       }
       this->api_connection_ = api_connection;
       this->enable_loop();
@@ -264,7 +394,15 @@ SerialProxyResult SerialProxy::serial_proxy_request(api::APIConnection *api_conn
         return SerialProxyResult::SERIAL_PROXY_RESULT_OK;
       }
       this->api_connection_ = nullptr;
+      this->reset_mode_();
+#ifdef USE_SERIAL_PROXY_TAP
+      // Keep the loop alive for a tap that still needs the port (mirrors loop())
+      if (this->tap_ == nullptr || !this->tap_->tap_needs_port()) {
+        this->disable_loop();
+      }
+#else
       this->disable_loop();
+#endif
       ESP_LOGV(TAG, "API connection unsubscribed from serial proxy [%" PRIu32 "]", this->instance_index_);
       return SerialProxyResult::SERIAL_PROXY_RESULT_OK;
     default:

esphome/components/serial_proxy/serial_proxy.h

@@ -26,6 +26,7 @@ class APIConnection;
 namespace enums {
 enum SerialProxyPortType : uint32_t;
 enum SerialProxyRequestType : uint32_t;
+enum SerialProxyMode : uint32_t;
 }  // namespace enums
 }  // namespace esphome::api
 
@@ -52,6 +53,36 @@ enum class SerialProxyResult : uint8_t {
 /// Maximum bytes to read from UART in a single loop iteration
 inline constexpr size_t SERIAL_PROXY_MAX_READ_SIZE = 256;
 
+#ifdef USE_SERIAL_PROXY_TAP
+/// Observes a port's traffic without owning it, and may inject bytes of its own.
+///
+/// This exists so protocol-aware behaviour can be layered onto a plain byte pipe without
+/// the pipe knowing anything about the protocol: the tap is compiled in only when some
+/// component asks for one, so a proxy carrying an RS485 meter pays nothing for it.
+///
+/// A tap is an observer, never a gatekeeper -- it cannot suppress or alter the bytes
+/// flowing in either direction, so a misbehaving tap cannot corrupt the stream.
+class SerialProxyTap {
+ public:
+  /// Bytes read from the device, before they are forwarded to any subscriber.
+  virtual void on_device_rx(const uint8_t *data, size_t len) = 0;
+
+  /// Bytes a subscriber sent towards the device, after they have been written.
+  virtual void on_client_tx(const uint8_t *data, size_t len) = 0;
+
+  /// True when the port must keep reading even with no subscriber attached, so a tap can
+  /// do its own protocol work while nobody is listening. Honoured only while no
+  /// subscriber holds the port; with one attached, the port mode alone decides.
+  virtual bool tap_needs_port() const = 0;
+
+  /// A client explicitly turned protocol handling off for this port. Distinct from the
+  /// automatic reset when a session ends: this one means a client intends to do something
+  /// else with the device -- reflash it, most likely -- so anything the tap believes about
+  /// it should be treated as suspect.
+  virtual void on_protocol_disabled() = 0;
+};
+#endif
+
 class SerialProxy final : public uart::UARTDevice, public Component {
  public:
   void setup() override;
@@ -77,6 +108,9 @@ class SerialProxy final : public uart::UARTDevice, public Component {
   /// Get the port type
   api::enums::SerialProxyPortType get_port_type() const { return this->port_type_; }
 
+  /// Handle a mode change requested by an API client
+  SerialProxyResult set_mode_from_client(api::APIConnection *api_connection, api::enums::SerialProxyMode mode);
+
   /// Configure UART parameters and apply them
   /// @param api_connection The API connection requesting the change
   /// @param baudrate Baud rate in bits per second
@@ -121,13 +155,67 @@ class SerialProxy final : public uart::UARTDevice, public Component {
   /// Set the DTR GPIO pin (from YAML configuration)
   void set_dtr_pin(GPIOPin *pin) { this->dtr_pin_ = pin; }
 
+#ifdef USE_SERIAL_PROXY_TAP
+  /// Attach a traffic observer. At most one, set once at setup time.
+  void set_tap(SerialProxyTap *tap) { this->tap_ = tap; }
+
+  /// Write bytes originating from the tap rather than from a client. Bypasses the
+  /// subscriber ownership check, but only while the tap is being served bytes -- so a
+  /// port in RAW mode with a subscriber attached stays inert. Returns false when the
+  /// bytes were dropped for that reason.
+  bool write_from_tap(const uint8_t *data, size_t len) {
+    if (!this->tap_observing_()) {
+      return false;
+    }
+    this->write_array(data, len);
+    return true;
+  }
+
+  /// Whether the tap is currently being served bytes. Can flip false with no callback
+  /// (a subscriber attaching in RAW mode, say), so a tap should check before starting
+  /// protocol work and when a reply seems overdue.
+  bool tap_is_observed() const { return this->tap_observing_(); }
+
+  /// Resume reading after a tap's needs change. loop() disables itself when there is
+  /// neither a subscriber nor a tap that wants the port, so a tap starting fresh work
+  /// must ask for it back. Must be called from the main loop.
+  void tap_request_port() { this->enable_loop(); }
+
+  /// Whether the underlying device is present. On a USB UART this tracks enumeration, so
+  /// a tap can notice the device being unplugged and plugged back in.
+  bool is_device_connected() const { return this->parent_->is_connected(); }
+
+  /// Run one read-and-dispatch cycle immediately. Lets a tap make progress before the
+  /// main loop is running -- during setup, for instance, while a component is still
+  /// blocking on can_proceed(). Must not be called from on_device_rx() or
+  /// on_client_tx(): each nested cycle costs a 256-byte stack frame.
+  void tap_pump();
+#endif
+
  protected:
 #ifdef USE_API
-  /// Read from UART and send to API client (slow path with 256-byte stack buffer)
+  /// Read from UART, hand the bytes to any tap, and forward them to a subscriber
+  /// (slow path with a 256-byte stack buffer)
   void read_and_send_(size_t available);
 
-  /// True when a live subscriber other than the given connection holds the port
-  bool port_claimed_by_other_(api::APIConnection *api_connection) const;
+  /// True when the given connection is the live subscriber. Every port operation
+  /// (write, configure, modem pins, flush, mode) requires this, so an unsubscribed
+  /// client can never share the wire with the subscriber or an active tap.
+  bool is_subscriber_(api::APIConnection *api_connection) const { return this->api_connection_ == api_connection; }
+#endif
+
+#ifdef USE_SERIAL_PROXY_TAP
+  /// Return the port to RAW when a subscriber goes away, so the mode never outlives it
+  void reset_mode_();
+#else
+  /// Without a tap, PROTOCOL is refused, so the mode is fixed at RAW and there is
+  /// nothing to reset
+  void reset_mode_() {}
+#endif
+
+#ifdef USE_SERIAL_PROXY_TAP
+  /// True when the tap should be shown the traffic passing through this port
+  bool tap_observing_() const;
 #endif
 
   /// Instance index for identifying this proxy in API messages
@@ -147,6 +235,11 @@ class SerialProxy final : public uart::UARTDevice, public Component {
   /// Port type
   api::enums::SerialProxyPortType port_type_{};
 
+#ifdef USE_SERIAL_PROXY_TAP
+  /// How the bytes passing through are treated; zero is SERIAL_PROXY_MODE_RAW
+  api::enums::SerialProxyMode mode_{};
+#endif
+
   /// Optional GPIO pins for modem control
   GPIOPin *rts_pin_{nullptr};
   GPIOPin *dtr_pin_{nullptr};
@@ -154,6 +247,10 @@ class SerialProxy final : public uart::UARTDevice, public Component {
   /// Current modem pin states
   bool rts_state_{false};
   bool dtr_state_{false};
+
+#ifdef USE_SERIAL_PROXY_TAP
+  SerialProxyTap *tap_{nullptr};
+#endif
 };
 
 }  // namespace esphome::serial_proxy

esphome/components/speaker/media_player/audio_pipeline.cpp

@@ -202,8 +202,15 @@ AudioPipelineState AudioPipeline::process_state() {
     if (!this->is_playing_) {
       // The tasks have been stopped for two ``process_state`` calls in a row, so delete the tasks
       if (this->read_task_.is_created() || this->decode_task_.is_created()) {
-        this->read_task_.deallocate();
-        this->decode_task_.deallocate();
+        // Both are attempted every time; a task that is still running on the other core is freed by a
+        // subsequent call, and freeing an already freed task succeeds without doing anything
+        bool read_task_freed = this->read_task_.deallocate();
+        bool decode_task_freed = this->decode_task_.deallocate();
+        if (!read_task_freed || !decode_task_freed) {
+          // A task is still running on the other core, so keep the pipeline in its current state and try
+          // again on the next call
+          return AudioPipelineState::PLAYING;
+        }
         if (this->hard_stop_) {
           // Stop command was sent, so immediately end the playback
           this->speaker_->stop();
@@ -315,17 +322,17 @@ void AudioPipeline::read_task(void *params) {
       if (err == ESP_OK) {
         size_t file_ring_buffer_size = this_pipeline->buffer_size_;
 
-        std::shared_ptr<ring_buffer::RingBuffer> temp_ring_buffer;
+        std::shared_ptr<ring_buffer::RingBuffer> temp_ring_buffer = this_pipeline->raw_file_ring_buffer_.lock();
 
-        if (!this_pipeline->raw_file_ring_buffer_.use_count()) {
+        if (temp_ring_buffer == nullptr) {
           temp_ring_buffer = ring_buffer::RingBuffer::create(file_ring_buffer_size);
           this_pipeline->raw_file_ring_buffer_ = temp_ring_buffer;
         }
 
-        if (!this_pipeline->raw_file_ring_buffer_.use_count()) {
+        if (temp_ring_buffer == nullptr) {
           err = ESP_ERR_NO_MEM;
         } else {
-          reader->add_sink(this_pipeline->raw_file_ring_buffer_);
+          err = reader->add_sink(temp_ring_buffer);
         }
       }
 
@@ -396,7 +403,9 @@ void AudioPipeline::decode_task(void *params) {
           make_unique<audio::AudioDecoder>(this_pipeline->transfer_buffer_size_, this_pipeline->transfer_buffer_size_);
 
       esp_err_t err = decoder->start(this_pipeline->current_audio_file_type_);
-      decoder->add_source(this_pipeline->raw_file_ring_buffer_);
+      if (err == ESP_OK) {
+        err = decoder->add_source(this_pipeline->raw_file_ring_buffer_);
+      }
 
       if (err != ESP_OK) {
         // Send specific error message

esphome/components/template/binary_sensor/__init__.py

@@ -2,7 +2,13 @@ from esphome import automation
 import esphome.codegen as cg
 from esphome.components import binary_sensor
 import esphome.config_validation as cv
-from esphome.const import CONF_CONDITION, CONF_ID, CONF_LAMBDA, CONF_STATE
+from esphome.const import (
+    CONF_CONDITION,
+    CONF_DEVICE_CLASS,
+    CONF_ID,
+    CONF_LAMBDA,
+    CONF_STATE,
+)
 from esphome.cpp_generator import LambdaExpression
 
 from .. import template_ns
@@ -12,7 +18,11 @@ TemplateBinarySensor = template_ns.class_(
 )
 
 CONFIG_SCHEMA = (
-    binary_sensor.binary_sensor_schema(TemplateBinarySensor)
+    cv.with_visibility(
+        binary_sensor.binary_sensor_schema(TemplateBinarySensor),
+        cv.Visibility.UI,
+        CONF_DEVICE_CLASS,
+    )
     .extend(
         {
             cv.Exclusive(CONF_LAMBDA, CONF_CONDITION): cv.returning_lambda,

esphome/components/template/button/__init__.py

@@ -1,10 +1,14 @@
 from esphome.components import button
+import esphome.config_validation as cv
+from esphome.const import CONF_DEVICE_CLASS
 
 from .. import template_ns
 
 TemplateButton = template_ns.class_("TemplateButton", button.Button)
 
-CONFIG_SCHEMA = button.button_schema(TemplateButton)
+CONFIG_SCHEMA = cv.with_visibility(
+    button.button_schema(TemplateButton), cv.Visibility.UI, CONF_DEVICE_CLASS
+)
 
 
 async def to_code(config):

esphome/components/template/cover/__init__.py

@@ -6,6 +6,7 @@ from esphome.const import (
     CONF_ASSUMED_STATE,
     CONF_CLOSE_ACTION,
     CONF_CURRENT_OPERATION,
+    CONF_DEVICE_CLASS,
     CONF_ID,
     CONF_LAMBDA,
     CONF_OPEN_ACTION,
@@ -38,7 +39,11 @@ CONF_HAS_POSITION = "has_position"
 CONF_TOGGLE_ACTION = "toggle_action"
 
 CONFIG_SCHEMA = (
-    cover.cover_schema(TemplateCover)
+    cv.with_visibility(
+        cover.cover_schema(TemplateCover),
+        cv.Visibility.UI,
+        CONF_DEVICE_CLASS,
+    )
     .extend(
         {
             cv.Optional(CONF_LAMBDA): cv.returning_lambda,

esphome/components/template/event/__init__.py

@@ -1,7 +1,7 @@
 import esphome.codegen as cg
 from esphome.components import event
 import esphome.config_validation as cv
-from esphome.const import CONF_EVENT_TYPES
+from esphome.const import CONF_DEVICE_CLASS, CONF_EVENT_TYPES
 
 from .. import template_ns
 
@@ -9,7 +9,9 @@ CODEOWNERS = ["@nohat"]
 
 TemplateEvent = template_ns.class_("TemplateEvent", event.Event, cg.Component)
 
-CONFIG_SCHEMA = event.event_schema(TemplateEvent).extend(
+CONFIG_SCHEMA = cv.with_visibility(
+    event.event_schema(TemplateEvent), cv.Visibility.UI, CONF_DEVICE_CLASS
+).extend(
     {
         cv.Required(CONF_EVENT_TYPES): cv.ensure_list(cv.string_strict),
     }

esphome/components/template/number/__init__.py

@@ -3,6 +3,7 @@ import esphome.codegen as cg
 from esphome.components import number
 import esphome.config_validation as cv
 from esphome.const import (
+    CONF_DEVICE_CLASS,
     CONF_ID,
     CONF_INITIAL_VALUE,
     CONF_LAMBDA,
@@ -12,6 +13,7 @@ from esphome.const import (
     CONF_RESTORE_VALUE,
     CONF_SET_ACTION,
     CONF_STEP,
+    CONF_UNIT_OF_MEASUREMENT,
 )
 
 from .. import template_ns
@@ -46,7 +48,12 @@ def validate(config):
 
 
 CONFIG_SCHEMA = cv.All(
-    number.number_schema(TemplateNumber)
+    cv.with_visibility(
+        number.number_schema(TemplateNumber),
+        cv.Visibility.UI,
+        CONF_DEVICE_CLASS,
+        CONF_UNIT_OF_MEASUREMENT,
+    )
     .extend(
         {
             cv.Required(CONF_MAX_VALUE): cv.float_,

esphome/components/template/sensor/__init__.py

@@ -2,7 +2,16 @@ from esphome import automation
 import esphome.codegen as cg
 from esphome.components import sensor
 import esphome.config_validation as cv
-from esphome.const import CONF_ID, CONF_LAMBDA, CONF_STATE
+from esphome.const import (
+    CONF_ACCURACY_DECIMALS,
+    CONF_DEVICE_CLASS,
+    CONF_FORCE_UPDATE,
+    CONF_ID,
+    CONF_LAMBDA,
+    CONF_STATE,
+    CONF_STATE_CLASS,
+    CONF_UNIT_OF_MEASUREMENT,
+)
 
 from .. import template_ns
 
@@ -11,9 +20,14 @@ TemplateSensor = template_ns.class_(
 )
 
 CONFIG_SCHEMA = (
-    sensor.sensor_schema(
-        TemplateSensor,
-        accuracy_decimals=1,
+    cv.with_visibility(
+        sensor.sensor_schema(TemplateSensor, accuracy_decimals=1),
+        cv.Visibility.UI,
+        CONF_UNIT_OF_MEASUREMENT,
+        CONF_ACCURACY_DECIMALS,
+        CONF_DEVICE_CLASS,
+        CONF_STATE_CLASS,
+        CONF_FORCE_UPDATE,
     )
     .extend(
         {

esphome/components/template/switch/__init__.py

@@ -4,6 +4,7 @@ from esphome.components import switch
 import esphome.config_validation as cv
 from esphome.const import (
     CONF_ASSUMED_STATE,
+    CONF_DEVICE_CLASS,
     CONF_ID,
     CONF_LAMBDA,
     CONF_OPTIMISTIC,
@@ -31,7 +32,11 @@ def validate(config):
 
 
 CONFIG_SCHEMA = cv.All(
-    switch.switch_schema(TemplateSwitch)
+    cv.with_visibility(
+        switch.switch_schema(TemplateSwitch),
+        cv.Visibility.UI,
+        CONF_DEVICE_CLASS,
+    )
     .extend(
         {
             cv.Optional(CONF_LAMBDA): cv.returning_lambda,

esphome/components/template/text_sensor/__init__.py

@@ -3,7 +3,7 @@ import esphome.codegen as cg
 from esphome.components import text_sensor
 from esphome.components.text_sensor import TextSensorPublishAction
 import esphome.config_validation as cv
-from esphome.const import CONF_ID, CONF_LAMBDA, CONF_STATE
+from esphome.const import CONF_DEVICE_CLASS, CONF_ID, CONF_LAMBDA, CONF_STATE
 
 from .. import template_ns
 
@@ -12,7 +12,11 @@ TemplateTextSensor = template_ns.class_(
 )
 
 CONFIG_SCHEMA = (
-    text_sensor.text_sensor_schema()
+    cv.with_visibility(
+        text_sensor.text_sensor_schema(),
+        cv.Visibility.UI,
+        CONF_DEVICE_CLASS,
+    )
     .extend(
         {
             cv.GenerateID(): cv.declare_id(TemplateTextSensor),

esphome/components/template/valve/__init__.py

@@ -6,6 +6,7 @@ from esphome.const import (
     CONF_ASSUMED_STATE,
     CONF_CLOSE_ACTION,
     CONF_CURRENT_OPERATION,
+    CONF_DEVICE_CLASS,
     CONF_ID,
     CONF_LAMBDA,
     CONF_OPEN_ACTION,
@@ -36,7 +37,11 @@ CONF_HAS_POSITION = "has_position"
 CONF_TOGGLE_ACTION = "toggle_action"
 
 CONFIG_SCHEMA = (
-    valve.valve_schema(TemplateValve)
+    cv.with_visibility(
+        valve.valve_schema(TemplateValve),
+        cv.Visibility.UI,
+        CONF_DEVICE_CLASS,
+    )
     .extend(
         {
             cv.Optional(CONF_LAMBDA): cv.returning_lambda,

esphome/components/zigbee/time/zigbee_time_zephyr.cpp

@@ -1,6 +1,7 @@
 #include "zigbee_time_zephyr.h"
 #if defined(USE_ZIGBEE) && defined(USE_NRF52) && defined(USE_TIME)
 #include "esphome/core/log.h"
+#include "esphome/core/application.h"
 
 namespace esphome::zigbee {
 
@@ -47,6 +48,7 @@ void ZigbeeTime::set_epoch_time(uint32_t epoch) {
     this->synchronize_epoch_(epoch);
     this->has_time_ = true;
   });
+  App.wake_loop_threadsafe();
 }
 
 void ZigbeeTime::zcl_device_cb_(zb_bufid_t bufid) {

esphome/components/zigbee/zigbee_esp32.cpp

@@ -49,7 +49,8 @@ void ZigbeeComponent::factory_reset() {
 
 void ZigbeeComponent::esp_zigbee_alarm_bdb_commissioning(ezb_bdb_comm_mode_mask_t mode) {
   if (!esp_zigbee_lock_acquire(10 / portTICK_PERIOD_MS)) {
-    global_zigbee->set_timeout("zb_init", 10, [mode]() { ZigbeeComponent::esp_zigbee_alarm_bdb_commissioning(mode); });
+    global_zigbee->set_timeout("zb_init", 100, [mode]() { ZigbeeComponent::esp_zigbee_alarm_bdb_commissioning(mode); });
+    App.wake_loop_threadsafe();
     return;
   }
   if (ezb_bdb_start_top_level_commissioning(mode) != EZB_ERR_NONE) {
@@ -88,6 +89,7 @@ bool ZigbeeComponent::app_signal_handler(const ezb_app_signal_t *app_signal) {
         global_zigbee->set_timeout("zb_init", 1000, []() {
           ZigbeeComponent::esp_zigbee_alarm_bdb_commissioning(EZB_BDB_MODE_INITIALIZATION);
         });
+        App.wake_loop_threadsafe();
       }
     } break;
     case EZB_BDB_SIGNAL_STEERING: {
@@ -113,6 +115,7 @@ bool ZigbeeComponent::app_signal_handler(const ezb_app_signal_t *app_signal) {
             ZigbeeComponent::esp_zigbee_alarm_bdb_commissioning(EZB_BDB_MODE_NETWORK_STEERING);
           });
         }
+        App.wake_loop_threadsafe();
       }
     } break;
     case EZB_ZDO_SIGNAL_LEAVE: {

esphome/components/zigbee/zigbee_zephyr.cpp

@@ -1,10 +1,10 @@
 #include "zigbee_zephyr.h"
 #if defined(USE_ZIGBEE) && defined(USE_NRF52)
 #include "esphome/core/log.h"
+#include "esphome/core/application.h"
 #include <zephyr/settings/settings.h>
 #include <zephyr/storage/flash_map.h>
 #include "esphome/core/hal.h"
-#include "esphome/core/wake.h"
 
 extern "C" {
 #include <zboss_api.h>
@@ -120,7 +120,7 @@ void ZigbeeComponent::zcl_device_cb(zb_bufid_t bufid) {
   /* Set default response value. */
   p_device_cb_param->status = RET_OK;
 
-  esphome::wake_loop_threadsafe();
+  App.wake_loop_threadsafe();
 
   // endpoints are enumerated from 1
   if (global_zigbee->callbacks_.size() >= endpoint) {
@@ -138,6 +138,7 @@ void ZigbeeComponent::on_join_(bool factory_new) {
     ESP_LOGD(TAG, "Joined the network");
     this->join_cb_.call(factory_new);
   });
+  App.wake_loop_threadsafe();
 }
 
 void ZigbeeComponent::on_start_() {
@@ -145,6 +146,7 @@ void ZigbeeComponent::on_start_() {
     ESP_LOGD(TAG, "Started zigbee stack");
     this->start_cb_.call();
   });
+  App.wake_loop_threadsafe();
 }
 
 #ifdef USE_ZIGBEE_WIPE_ON_BOOT

esphome/config_validation.py

@@ -4,6 +4,7 @@ from __future__ import annotations
 
 from collections.abc import Callable
 from contextlib import contextmanager, suppress
+import copy
 from datetime import datetime
 from ipaddress import (
     AddressValueError,
@@ -419,6 +420,37 @@ class Required(vol.Required):
         self.visibility: Visibility | None = visibility
 
 
+def with_visibility(schema: Schema, visibility: Visibility, *keys: str) -> Schema:
+    """Return a copy of ``schema`` with the given ``keys`` re-marked at ``visibility``.
+
+    Lets a platform override the editor :class:`Visibility` of fields it
+    inherits from a shared schema builder — without that builder needing a
+    visibility parameter of its own. The canonical use is a ``template``
+    platform promoting the value metadata its user is expected to define
+    (``device_class``, ``unit_of_measurement``, …) onto the main form:
+
+        CONFIG_SCHEMA = cv.with_visibility(
+            sensor.sensor_schema(TemplateSensor),
+            cv.Visibility.UI,
+            CONF_DEVICE_CLASS, CONF_UNIT_OF_MEASUREMENT,
+        )
+
+    The original marker's key, default and validator are preserved; only the
+    visibility changes, and the input ``schema`` is left untouched. Raises if
+    a requested key is not present so typos fail at schema-build time.
+    """
+    wanted = {str(k) for k in keys}
+    overrides = {}
+    for marker, validator in schema.schema.items():
+        if str(marker) in wanted:
+            marker = copy.copy(marker)
+            marker.visibility = visibility
+            overrides[marker] = validator
+    if missing := wanted - {str(m) for m in overrides}:
+        raise ValueError(f"with_visibility: keys not in schema: {sorted(missing)}")
+    return schema.extend(overrides)
+
+
 class FinalExternalInvalid(Invalid):
     """Represents an invalid value in the final validation phase where the path should not be prepended."""
 

esphome/core/defines.h

@@ -181,6 +181,7 @@
 #define USE_SENSOR
 #define USE_SENSOR_FILTER
 #define USE_SERIAL_PROXY
+#define USE_SERIAL_PROXY_TAP
 #define USE_SETUP_PRIORITY_OVERRIDE
 #define USE_STATUS_LED
 #define USE_STATUS_SENSOR

esphome/core/static_task.cpp

@@ -40,16 +40,31 @@ bool StaticTask::create(TaskFunction_t fn, const char *name, uint32_t stack_size
   return true;
 }
 
-void StaticTask::destroy() {
-  if (this->handle_ != nullptr) {
-    TaskHandle_t handle = this->handle_;
-    this->handle_ = nullptr;
-    vTaskDelete(handle);
+bool StaticTask::destroy() {
+  if (this->handle_ == nullptr) {
+    return true;
   }
+
+  // Suspending takes the task off the ready and event lists, so nothing can schedule it again. It only asks
+  // the other core to yield though, so the task may still be running on it for a moment.
+  vTaskSuspend(this->handle_);
+  if (eTaskGetState(this->handle_) != eSuspended) {
+    // The task is still running on the other core and using its stack. Deleting it now would only put it on
+    // the termination list and return, so the caller has to try again once it has been swapped out.
+    return false;
+  }
+
+  // The task cannot run again, so the delete completes right away instead of being left to the idle task.
+  TaskHandle_t handle = this->handle_;
+  this->handle_ = nullptr;
+  vTaskDelete(handle);
+  return true;
 }
 
-void StaticTask::deallocate() {
-  this->destroy();
+bool StaticTask::deallocate() {
+  if (!this->destroy()) {
+    return false;
+  }
   if (this->stack_buffer_ != nullptr) {
     RAMAllocator<StackType_t> allocator(this->use_psram_ ? RAMAllocator<StackType_t>::ALLOC_EXTERNAL
                                                          : RAMAllocator<StackType_t>::ALLOC_INTERNAL);
@@ -57,6 +72,7 @@ void StaticTask::deallocate() {
     this->stack_buffer_ = nullptr;
     this->stack_size_ = 0;
   }
+  return true;
 }
 
 }  // namespace esphome

esphome/core/static_task.h

@@ -11,6 +11,7 @@ namespace esphome {
 
 /** Helper for FreeRTOS static task management.
  * Bundles TaskHandle_t, StaticTask_t, and the stack buffer into one object with create/destroy methods.
+ * Call destroy() and deallocate() from another task: a task cannot free the stack it is still running on.
  */
 class StaticTask {
  public:
@@ -23,7 +24,7 @@ class StaticTask {
   /// @brief Allocate stack and create task.
   /// @param fn         Task function
   /// @param name       Task name (for debug)
-  /// @param stack_size Stack size in StackType_t words
+  /// @param stack_size Stack size in bytes (StackType_t is a byte on ESP-IDF)
   /// @param param      Parameter passed to task function
   /// @param priority   FreeRTOS task priority
   /// @param use_psram  If true, allocate stack in PSRAM; otherwise internal RAM
@@ -31,11 +32,17 @@ class StaticTask {
   bool create(TaskFunction_t fn, const char *name, uint32_t stack_size, void *param, UBaseType_t priority,
               bool use_psram);
 
-  /// @brief Delete the task but keep the stack buffer allocated for reuse by a subsequent create() call.
-  void destroy();
+  /// @brief Delete the task, keeping the stack buffer allocated for reuse by a subsequent create() call.
+  /// The task must have finished its work and parked itself, either suspended or blocked indefinitely: it is
+  /// suspended here so that it cannot be scheduled again, and it is given no chance to clean up.
+  /// @return true if the task was deleted; false if it is still running on another core, in which case the
+  /// caller should try again later.
+  bool destroy();
 
-  /// @brief Delete the task (if running) and free the stack buffer.
-  void deallocate();
+  /// @brief Delete the task (if created) and free the stack buffer.
+  /// @return true if the stack buffer was freed; false if the task is still running on another core, in
+  /// which case the caller should try again later.
+  bool deallocate();
 
  protected:
   TaskHandle_t handle_{nullptr};

esphome/core/string_ref.h

@@ -22,6 +22,10 @@ namespace esphome {
  * pointer.  When it is default constructed, it has empty string.  You can freely copy or move around this struct, but
  * never free its pointer.  str() function can be used to export the content as std::string. StringRef is adopted from
  * <https://github.com/nghttp2/nghttp2/blob/29cbf8b83ff78faf405d1086b16adc09a8772eca/src/template.h#L376>
+ *
+ * A StringRef may carry a null pointer while its length is zero (the generated api messages start their encode only
+ * string fields that way). Every member treats that as the empty string; only c_str() hands the null pointer on, so
+ * callers that print or copy through c_str() must check empty() first.
  */
 class StringRef {
  public:
@@ -78,7 +82,7 @@ class StringRef {
 
   /// True if the view begins with the given prefix (std::string::starts_with-like)
   bool starts_with(const StringRef &prefix) const {
-    return len_ >= prefix.len_ && std::memcmp(base_, prefix.base_, prefix.len_) == 0;
+    return len_ >= prefix.len_ && (prefix.len_ == 0 || std::memcmp(base_, prefix.base_, prefix.len_) == 0);
   }
   bool starts_with(const char *prefix) const { return this->starts_with(StringRef(prefix)); }
   bool starts_with(const std::string &prefix) const { return this->starts_with(StringRef(prefix)); }
@@ -92,14 +96,15 @@ class StringRef {
     return actual;
   }
 
-  std::string str() const { return std::string(base_, len_); }
+  std::string str() const { return std::string(base_, len_); }  // fine for {nullptr, 0}: nothing is read
   const uint8_t *byte() const { return reinterpret_cast<const uint8_t *>(base_); }
 
   operator std::string() const { return str(); }
 
   /// Compare (compatible with std::string::compare)
   int compare(const StringRef &other) const {
-    int result = std::memcmp(base_, other.base_, std::min(len_, other.len_));
+    size_type common = std::min(len_, other.len_);
+    int result = common == 0 ? 0 : std::memcmp(base_, other.base_, common);
     if (result != 0)
       return result;
     if (len_ < other.len_)
@@ -258,7 +263,14 @@ inline double stod(const StringRef &str, size_t *pos = nullptr) {
 
 #ifdef USE_JSON
 // NOLINTNEXTLINE(readability-identifier-naming)
-inline void convertToJson(const StringRef &src, JsonVariant dst) { dst.set(src.c_str()); }
+inline void convertToJson(const StringRef &src, JsonVariant dst) {
+  // Bounded by the view length; a null, empty view becomes "" rather than JSON null
+  if (src.empty()) {
+    dst.set("");
+    return;
+  }
+  dst.set(JsonString(src.c_str(), src.size()));
+}
 #endif  // USE_JSON
 
 }  // namespace esphome

esphome/espota2.py

@@ -96,6 +96,10 @@ UPLOAD_BUFFER_SIZE = UPLOAD_BLOCK_SIZE * 8
 # across the addresses on top of that.
 EXTRA_UPLOAD_ATTEMPTS = 2
 UPLOAD_RETRY_DELAY = 5.0
+# Data phase timeout; must stay longer than the device's OTA_SOCKET_TIMEOUT_DATA
+# (105 s) so a stalled session is gone before a retry, and long enough for lwIP
+# to get a lost chunk ack through after the retransmit run seen in practice
+DATA_PHASE_TIMEOUT = 160.0
 
 _LOGGER = logging.getLogger(__name__)
 
@@ -694,8 +698,7 @@ def perform_ota(
 
     _LOGGER.info("Handshake complete")
 
-    # Timeout must match device-side OTA_SOCKET_TIMEOUT_DATA to prevent premature failures
-    sock.settimeout(90.0)
+    sock.settimeout(DATA_PHASE_TIMEOUT)
 
     if extended_proto:
         send_check(sock, ota_type, "ota type")
@@ -854,7 +857,7 @@ def run_ota_impl_(
     # clean up a half-open connection (its handshake watchdog runs at 20s);
     # moving on to the next address family stays immediate. Known limitation:
     # a silent mid-transfer drop with no reset can wedge the device until its
-    # 90s data timeout, which outlasts this budget; the retries target the
+    # 105s data timeout, which outlasts this budget; the retries target the
     # common failures where the device resets or closes the link promptly.
     total_attempts = len(res) + EXTRA_UPLOAD_ATTEMPTS
     last_error = ""

platformio.ini

@@ -45,7 +45,7 @@ lib_deps_base =
 lib_deps =
     ${common.lib_deps_base}
     https://github.com/dudanov/MideaUART.git#eeea6c3e9b4474f067054592b435be1c4e466815 ; midea
-    esphome/noise-c@0.1.24                 ; noise (api, ota)
+    esphome/noise-c@0.1.26                 ; noise (api, ota)
     improv/Improv@1.2.7                    ; improv_serial / esp32_improv
     kikuchan98/pngle@1.1.0                 ; online_image
     ; Using the repository directly, otherwise ESP-IDF can't use the library
@@ -244,7 +244,7 @@ lib_deps =
     ${common:idf-component-libs.lib_deps}
     ESP32Async/ESPAsyncWebServer@3.9.6    ; web_server_base
     droscy/esp_wireguard@0.4.5            ; wireguard
-    esphome/noise-c@0.1.24                ; noise (api, ota)
+    esphome/noise-c@0.1.26                ; noise (api, ota)
     ESP32Async/AsyncTCP@3.4.5             ; async_tcp
     DNSServer                             ; captive_portal
     heman/AsyncMqttClient-esphome@2.0.0   ; mqtt
@@ -641,7 +641,7 @@ build_unflags =
 extends = common
 platform = platformio/native
 lib_deps =
-    esphome/noise-c@0.1.24  ; used by noise (api, ota)
+    esphome/noise-c@0.1.26  ; used by noise (api, ota)
     lvgl/lvgl@9.5.0         ; lvgl
 build_flags =
     ${common.build_flags}

requirements.txt

@@ -10,9 +10,9 @@ tzlocal==5.4.4    # from time
 tzdata>=2026.3  # from time
 pyserial==3.5
 platformio==6.1.19
-esptool==5.3.1
+esptool==5.4.0
 click==8.3.3
-aioesphomeapi==46.3.0
+aioesphomeapi==46.4.0
 aiohappyeyeballs==2.7.1  # Happy Eyeballs for requests downloads; already pulled in by aioesphomeapi
 zeroconf==0.151.3
 puremagic==2.2.0

script/api_protobuf/api_protobuf.py

@@ -28,6 +28,11 @@ class WireType(IntEnum):
     END_GROUP = 4  # groups (deprecated)
     FIXED32 = 5  # fixed32, sfixed32, float
 
+    @property
+    def cpp_name(self) -> str:
+        """The matching constant in proto.h."""
+        return f"WIRE_TYPE_{self.name}"
+
 
 # Generate with
 # protoc --python_out=script/api_protobuf -I esphome/components/api/ api_options.proto
@@ -126,9 +131,10 @@ def camel_to_snake(name: str) -> str:
     return re.sub("([a-z0-9])([A-Z])", r"\1_\2", s1).lower()
 
 
-def force_str(force: bool) -> str:
-    """Convert a boolean force value to string format for C++ code."""
-    return str(force).lower()
+def _encode_call(func: str, *args: str, force: bool = False) -> str:
+    """Emit one ProtoEncode call; every helper takes the cursor and returns it advanced."""
+    suffix = "_force" if force else ""
+    return f"pos = ProtoEncode::{func}{suffix}({', '.join(('pos', *args))});"
 
 
 class TypeInfo(ABC):
@@ -223,55 +229,39 @@ class TypeInfo(ABC):
     def class_member(self) -> str:
         return f"{self.cpp_type} {self.field_name}{{{self.default_value}}};"
 
-    @property
-    def decode_varint_content(self) -> str:
-        content = self.decode_varint
-        if content is None:
-            return None
-        return f"case {self.number}: this->{self.field_name} = {content}; break;"
+    def decode_case(self, body: str) -> str:
+        """Emit one decode_field() case, keyed on the field's wire tag."""
+        return f"case proto_tag({self.number}, {self.wire_type.cpp_name}):\n" + indent(
+            f"{body}\nbreak;"
+        )
 
-    decode_varint = None
+    # Expression that reads this field from `value`; None when the type is never decoded.
+    decode_expr: str | None = None
+
+    def _decode_store(self, expr: str) -> str:
+        return f"this->{self.field_name} = {expr};"
 
     @property
-    def decode_length_content(self) -> str:
-        content = self.decode_length
-        if content is None:
-            return None
-        return f"case {self.number}: this->{self.field_name} = {content}; break;"
-
-    decode_length = None
-
-    @property
-    def decode_32bit_content(self) -> str:
-        content = self.decode_32bit
-        if content is None:
-            return None
-        return f"case {self.number}: this->{self.field_name} = {content}; break;"
-
-    decode_32bit = None
-
-    @property
-    def decode_64bit_content(self) -> str:
-        content = self.decode_64bit
-        if content is None:
-            return None
-        return f"case {self.number}: this->{self.field_name} = {content}; break;"
-
-    decode_64bit = None
+    def decode_content(self) -> str | None:
+        """The decode_field() case for this field, or None when it is never decoded."""
+        expr = self.decode_expr
+        return None if expr is None else self.decode_case(self._decode_store(expr))
 
     # Mapping from encode_func to raw encode expression template.
     # When a forced field has a single-byte tag, the code generator emits
     # write_raw_byte(tag) + raw encode instead of the full encode_* method,
     # eliminating the zero-check branch and encode_field_raw indirection.
     # {value} is replaced with the actual field expression.
-    RAW_ENCODE_MAP: dict[str, str] = {
-        "encode_uint32": "ProtoEncode::encode_varint_raw(pos, {value});",
-        "encode_uint64": "ProtoEncode::encode_varint_raw_64(pos, {value});",
-        "encode_sint32": "ProtoEncode::encode_varint_raw_short(pos, encode_zigzag32({value}));",
-        "encode_sint64": "ProtoEncode::encode_varint_raw_64(pos, encode_zigzag64({value}));",
-        "encode_int64": "ProtoEncode::encode_varint_raw_64(pos, static_cast<uint64_t>({value}));",
-        "encode_bool": "ProtoEncode::write_raw_byte(pos, {value} ? 0x01 : 0x00);",
+    RAW_ENCODE_MAP: dict[str, tuple[str, str]] = {
+        "encode_uint32": ("encode_varint_raw", "{value}"),
+        "encode_uint64": ("encode_varint_raw_64", "{value}"),
+        "encode_sint32": ("encode_varint_raw_short", "encode_zigzag32({value})"),
+        "encode_sint64": ("encode_varint_raw_64", "encode_zigzag64({value})"),
+        "encode_int64": ("encode_varint_raw_64", "static_cast<uint64_t>({value})"),
+        "encode_bool": ("write_raw_byte", "{value} ? 0x01 : 0x00"),
     }
+    # Fixed32 value expression for the shared tag+fixed32 writer; None for other wire types
+    fixed32_value_template: str | None = None
 
     def _encode_with_precomputed_tag(self, value_expr: str) -> str | None:
         """Try to emit a precomputed-tag encode for a field.
@@ -288,12 +278,17 @@ class TypeInfo(ABC):
             return None
         max_val = self.max_value
         # Only use RAW_ENCODE_MAP for forced fields or fields with max_value
-        raw_expr = None
+        raw = None
         if self.force or max_val is not None:
-            raw_expr = self.RAW_ENCODE_MAP.get(self.encode_func)
-        if raw_expr is None:
+            raw = self.RAW_ENCODE_MAP.get(self.encode_func)
+        if raw is None:
             return None
-        body = f"ProtoEncode::write_raw_byte(pos, {tag});\n{raw_expr.format(value=value_expr)}"
+        func, arg = raw
+        body = (
+            _encode_call("write_raw_byte", str(tag))
+            + "\n"
+            + _encode_call(func, arg.format(value=value_expr))
+        )
         if self.force:
             return body
         # Non-forced with max_value: inline zero-check + raw encode
@@ -314,23 +309,44 @@ class TypeInfo(ABC):
             return None
         # When max_len < 128, length varint is always 1 byte
         len_encode = (
-            f"ProtoEncode::write_raw_byte(pos, static_cast<uint8_t>({len_expr}));"
+            _encode_call("write_raw_byte", f"static_cast<uint8_t>({len_expr})")
             if max_len is not None and max_len < 128
-            else f"ProtoEncode::encode_varint_raw(pos, {len_expr});"
+            else _encode_call("encode_varint_raw", len_expr)
         )
+        return "\n".join(
+            (
+                _encode_call("write_raw_byte", str(tag)),
+                len_encode,
+                _encode_call("encode_raw", data_expr, len_expr),
+            )
+        )
+
+    def _encode_fixed32_with_precomputed_tag(self, value: str) -> str | None:
+        """Single-byte tag fixed32 write, or None for other types and multi-byte tags."""
+        tag = self.calculate_tag()
+        if self.fixed32_value_template is None or tag >= 128:
+            return None
+        value_expr = self.fixed32_value_template.format(value=value)
+        if self.force:
+            return _encode_call("write_tag_and_fixed32", str(tag), value_expr)
         return (
-            f"ProtoEncode::write_raw_byte(pos, {tag});\n"
-            f"{len_encode}\n"
-            f"ProtoEncode::encode_raw(pos, {data_expr}, {len_expr});"
+            f"if (uint32_t raw = {value_expr}; raw != 0) [[likely]] {{\n"
+            f"  {_encode_call('write_tag_and_fixed32', str(tag), 'raw')}\n"
+            "}"
         )
 
     @property
     def encode_content(self) -> str:
-        if result := self._encode_with_precomputed_tag(f"this->{self.field_name}"):
+        value = f"this->{self.field_name}"
+        if result := self._encode_with_precomputed_tag(value):
             return result
-        if self.force:
-            return f"ProtoEncode::{self.encode_func}(pos, {self.number}, this->{self.field_name}, true);"
-        return f"ProtoEncode::{self.encode_func}(pos, {self.number}, this->{self.field_name});"
+        if result := self._encode_fixed32_with_precomputed_tag(value):
+            return result
+        return _encode_call(self.encode_func, str(self.number), value, force=self.force)
+
+    def encode_element(self, number: int, element: str) -> str:
+        """Encode one element of a repeated field; elements are always written."""
+        return _encode_call(self.encode_func, str(number), element, force=True)
 
     encode_func = None
 
@@ -550,17 +566,17 @@ def create_field_type_info(
         # For messages that decode (SOURCE_CLIENT or SOURCE_BOTH), use pointer
         # for zero-copy access to the receive buffer
         if needs_decode:
-            return PointerToBytesBufferType(field, None)
+            return PointerToBytesBufferType(field, needs_decode)
 
         # For SOURCE_SERVER (encode only), explicit annotation is still needed
         if get_field_opt(field, pb.pointer_to_buffer, False):
-            return PointerToBytesBufferType(field, None)
+            return PointerToBytesBufferType(field, needs_decode)
 
         return BytesType(field, needs_decode, needs_encode)
 
     # Special handling for string fields - use StringRef for zero-copy
     if field.type == 9:
-        return PointerToStringBufferType(field, None)
+        return PointerToStringBufferType(field, needs_decode)
 
     validate_field_type(field.type, field.name)
     if field.type == 11:
@@ -605,7 +621,6 @@ class DoubleType(FixedSizeTypeMixin, TypeInfo):
     # Unsupported but defined for completeness
     cpp_type = "double"
     default_value = "0.0"
-    decode_64bit = "value.as_double()"
     encode_func = "encode_double"
     wire_type = WireType.FIXED64  # Uses wire type 1 according to protobuf spec
 
@@ -631,10 +646,12 @@ class DoubleType(FixedSizeTypeMixin, TypeInfo):
 class FloatType(FixedSizeTypeMixin, TypeInfo):
     cpp_type = "float"
     default_value = "0.0f"
-    decode_32bit = "value.as_float()"
+    decode_expr = "value.as_float()"
     encode_func = "encode_float"
     wire_type = WireType.FIXED32  # Uses wire type 5
 
+    fixed32_value_template = "float_to_raw({value})"
+
     def dump(self, name: str) -> str:
         o = f'snprintf(buffer, sizeof(buffer), "%g", {name});\n'
         o += "out.append(buffer);"
@@ -658,7 +675,7 @@ class Int64Type(VarintTypeMixin, TypeInfo):
     cpp_type = "int64_t"
     _varint_max_bits = 64
     default_value = "0"
-    decode_varint = "static_cast<int64_t>(value)"
+    decode_expr = "static_cast<int64_t>(value.as_varint())"
     encode_func = "encode_int64"
     wire_type = WireType.VARINT  # Uses wire type 0
 
@@ -679,7 +696,7 @@ class UInt64Type(VarintTypeMixin, TypeInfo):
     cpp_type = "uint64_t"
     _varint_max_bits = 64
     default_value = "0"
-    decode_varint = "value"
+    decode_expr = "value.as_varint()"
     encode_func = "encode_uint64"
     wire_type = WireType.VARINT  # Uses wire type 0
 
@@ -697,11 +714,11 @@ class UInt64Type(VarintTypeMixin, TypeInfo):
         return self._get_simple_size_calculation(name, force, "uint64")
 
     @property
-    def RAW_ENCODE_MAP(self) -> dict[str, str]:  # noqa: N802
+    def RAW_ENCODE_MAP(self) -> dict[str, tuple[str, str]]:  # noqa: N802
         if self.mac_address:
             return {
                 **TypeInfo.RAW_ENCODE_MAP,
-                "encode_uint64": "ProtoEncode::encode_varint_raw_48bit(pos, {value});",
+                "encode_uint64": ("encode_varint_raw_48bit", "{value}"),
             }
         return TypeInfo.RAW_ENCODE_MAP
 
@@ -714,7 +731,7 @@ class Int32Type(VarintTypeMixin, TypeInfo):
     cpp_type = "int32_t"
     _varint_max_bits = 64  # int32 is sign-extended to 64 bits in protobuf
     default_value = "0"
-    decode_varint = "static_cast<int32_t>(value)"
+    decode_expr = "static_cast<int32_t>(value.as_varint())"
     encode_func = "encode_int32"
     wire_type = WireType.VARINT  # Uses wire type 0
 
@@ -734,7 +751,6 @@ class Int32Type(VarintTypeMixin, TypeInfo):
 class Fixed64Type(FixedSizeTypeMixin, TypeInfo):
     cpp_type = "uint64_t"
     default_value = "0"
-    decode_64bit = "value.as_fixed64()"
     encode_func = "encode_fixed64"
     wire_type = WireType.FIXED64  # Uses wire type 1
 
@@ -760,7 +776,7 @@ class Fixed64Type(FixedSizeTypeMixin, TypeInfo):
 class Fixed32Type(FixedSizeTypeMixin, TypeInfo):
     cpp_type = "uint32_t"
     default_value = "0"
-    decode_32bit = "value.as_fixed32()"
+    decode_expr = "value.as_fixed32()"
     encode_func = "encode_fixed32"
     wire_type = WireType.FIXED32  # Uses wire type 5
 
@@ -769,15 +785,7 @@ class Fixed32Type(FixedSizeTypeMixin, TypeInfo):
         o += "out.append(buffer);"
         return o
 
-    @property
-    def encode_content(self) -> str:
-        tag = self.calculate_tag()
-        if self.force and tag < 128:
-            # Emit combined tag+value write: precomputed tag + direct memcpy
-            return f"ProtoEncode::write_tag_and_fixed32(pos, {tag}, this->{self.field_name});"
-        if self.force:
-            return f"ProtoEncode::{self.encode_func}(pos, {self.number}, this->{self.field_name}, true);"
-        return f"ProtoEncode::{self.encode_func}(pos, {self.number}, this->{self.field_name});"
+    fixed32_value_template = "{value}"
 
     def get_size_calculation(self, name: str, force: bool = False) -> str:
         field_id_size = self.calculate_field_id_size()
@@ -797,7 +805,7 @@ class BoolType(VarintTypeMixin, TypeInfo):
     _varint_max_bits = 1
     cpp_type = "bool"
     default_value = "false"
-    decode_varint = "value != 0"
+    decode_expr = "value.as_bool()"
     encode_func = "encode_bool"
     wire_type = WireType.VARINT  # Uses wire type 0
 
@@ -817,7 +825,7 @@ class StringType(TypeInfo):
     default_value = ""
     reference_type = "std::string &"
     const_reference_type = "const std::string &"
-    decode_length = "value.as_string()"
+    decode_expr = "value.as_string()"
     encode_func = "encode_string"
     wire_type = WireType.LENGTH_DELIMITED  # Uses wire type 2
 
@@ -851,9 +859,12 @@ class StringType(TypeInfo):
             f"this->{self.field_name}_ref_.size()",
         ):
             return result
-        if self.force:
-            return f"ProtoEncode::encode_string(pos, {self.number}, this->{self.field_name}_ref_, true);"
-        return f"ProtoEncode::encode_string(pos, {self.number}, this->{self.field_name}_ref_);"
+        return _encode_call(
+            "encode_string",
+            str(self.number),
+            f"this->{self.field_name}_ref_",
+            force=self.force,
+        )
 
     def dump(self, name):
         # If name is 'it', this is a repeated field element - always use string
@@ -929,6 +940,9 @@ class MessageType(TypeInfo):
     def can_use_dump_field(cls) -> bool:
         return False
 
+    def encode_element(self, number: int, element: str) -> str:
+        return _encode_call("encode_sub_message", "buffer", str(number), element)
+
     @property
     def cpp_type(self) -> str:
         return self._field.type_name[1:]
@@ -951,15 +965,9 @@ class MessageType(TypeInfo):
     @property
     def encode_content(self) -> str:
         # Sub-message encoding needs buffer for backpatch/sync
-        return f"ProtoEncode::{self.encode_func}(pos, buffer, {self.number}, this->{self.field_name});"
-
-    @property
-    def decode_length(self) -> str:
-        # Override to return None for message types because we can't use template-based
-        # decoding when the specific message type isn't known at compile time.
-        # Instead, we use the non-template decode_to_message() method which allows
-        # runtime polymorphism through virtual function calls.
-        return None
+        return _encode_call(
+            self.encode_func, "buffer", str(self.number), f"this->{self.field_name}"
+        )
 
     @property
     def public_content(self) -> list[str]:
@@ -976,19 +984,14 @@ class MessageType(TypeInfo):
         )
 
     @property
-    def decode_length_content(self) -> str:
-        # Custom decode that doesn't use templates
+    def decode_content(self) -> str:
+        body = f"value.decode_to_message(this->{self.field_name});"
         if self._track_presence:
             # decode_to_message() cannot report failure, so setting the flag
             # afterwards only documents intent; a status-returning decode could
             # gate it for real without touching callers.
-            return (
-                f"case {self.number}:\n"
-                f"      value.decode_to_message(this->{self.field_name});\n"
-                f"      this->has_{self.name} = true;\n"
-                f"      break;"
-            )
-        return f"case {self.number}: value.decode_to_message(this->{self.field_name}); break;"
+            body += f"\nthis->has_{self.name} = true;"
+        return self.decode_case(body)
 
     def dump(self, name: str) -> str:
         return f"{name}.dump_to(out);"
@@ -1027,7 +1030,7 @@ class BytesType(TypeInfo):
     reference_type = "std::string &"
     const_reference_type = "const std::string &"
     encode_func = "encode_bytes"
-    decode_length = "value.as_string()"
+    decode_expr = "value.as_string()"
     wire_type = WireType.LENGTH_DELIMITED  # Uses wire type 2
 
     @property
@@ -1058,9 +1061,13 @@ class BytesType(TypeInfo):
             f"this->{self.field_name}_ptr_", f"this->{self.field_name}_len_"
         ):
             return result
-        if self.force:
-            return f"ProtoEncode::encode_bytes(pos, {self.number}, this->{self.field_name}_ptr_, this->{self.field_name}_len_, true);"
-        return f"ProtoEncode::encode_bytes(pos, {self.number}, this->{self.field_name}_ptr_, this->{self.field_name}_len_);"
+        return _encode_call(
+            "encode_bytes",
+            str(self.number),
+            f"this->{self.field_name}_ptr_",
+            f"this->{self.field_name}_len_",
+            force=self.force,
+        )
 
     def dump(self, name: str) -> str:
         ptr_dump = f"format_hex_pretty(this->{self.field_name}_ptr_, this->{self.field_name}_len_)"
@@ -1127,16 +1134,12 @@ class PointerToBufferTypeBase(TypeInfo):
     def can_use_dump_field(cls) -> bool:
         return False
 
+    # Only here to make needs_decode required: the null string default keys off it, so a call
+    # site must not fall back on the base class default
     def __init__(
-        self, field: descriptor.FieldDescriptorProto, size: int | None = None
+        self, field: descriptor.FieldDescriptorProto, needs_decode: bool
     ) -> None:
-        super().__init__(field)
-        self.array_size = 0
-
-    @property
-    def decode_length(self) -> str | None:
-        # This is handled in decode_length_content
-        return None
+        super().__init__(field, needs_decode)
 
     @property
     def wire_type(self) -> WireType:
@@ -1170,17 +1173,20 @@ class PointerToBytesBufferType(PointerToBufferTypeBase):
             f"this->{self.field_name}", f"this->{self.field_name}_len"
         ):
             return result
-        if self.force:
-            return f"ProtoEncode::encode_bytes(pos, {self.number}, this->{self.field_name}, this->{self.field_name}_len, true);"
-        return f"ProtoEncode::encode_bytes(pos, {self.number}, this->{self.field_name}, this->{self.field_name}_len);"
+        return _encode_call(
+            "encode_bytes",
+            str(self.number),
+            f"this->{self.field_name}",
+            f"this->{self.field_name}_len",
+            force=self.force,
+        )
 
     @property
-    def decode_length_content(self) -> str | None:
-        return f"""case {self.number}: {{
-      this->{self.field_name} = value.data();
-      this->{self.field_name}_len = value.size();
-      break;
-    }}"""
+    def decode_content(self) -> str:
+        return self.decode_case(
+            f"this->{self.field_name} = value.data();\n"
+            f"this->{self.field_name}_len = value.size();",
+        )
 
     def dump(self, name: str) -> str:
         return (
@@ -1214,34 +1220,53 @@ class PointerToStringBufferType(PointerToBufferTypeBase):
     def can_use_dump_field(cls) -> bool:
         return True
 
+    @property
+    def _starts_null(self) -> bool:
+        """A field that is only encoded, and skipped when empty, never has its pointer read
+        before it is set, so it can default to a null StringRef and the message constructs as
+        one zero fill. Any encode path that copies unconditionally must check this."""
+        return not self._needs_decode and not self.force
+
     @property
     def public_content(self) -> list[str]:
+        if self._starts_null:
+            return [
+                f"StringRef {self.field_name}{{nullptr, 0}};  // null until set, encode only"
+            ]
         return [f"StringRef {self.field_name}{{}};"]
 
     @property
     def encode_content(self) -> str:
         max_len = self.max_data_length
         if max_len is not None and max_len < 128 and self.force:
+            assert not self._starts_null, (
+                "unconditional copy of a field that may start null"
+            )
             tag = self.calculate_tag()
             if tag < 128:
-                return f"ProtoEncode::encode_short_string_force(pos, {tag}, this->{self.field_name});"
+                return _encode_call(
+                    "encode_short_string_force", str(tag), f"this->{self.field_name}"
+                )
         if result := self._encode_bytes_with_precomputed_tag(
             f"this->{self.field_name}.c_str()",
             f"this->{self.field_name}.size()",
         ):
+            assert not self._starts_null, (
+                "unconditional copy of a field that may start null"
+            )
             return result
-        if self.force:
-            return f"ProtoEncode::encode_string(pos, {self.number}, this->{self.field_name}, true);"
-        return (
-            f"ProtoEncode::encode_string(pos, {self.number}, this->{self.field_name});"
+        return _encode_call(
+            "encode_string",
+            str(self.number),
+            f"this->{self.field_name}",
+            force=self.force,
         )
 
     @property
-    def decode_length_content(self) -> str | None:
-        return f"""case {self.number}: {{
-      this->{self.field_name} = StringRef(reinterpret_cast<const char *>(value.data()), value.size());
-      break;
-    }}"""
+    def decode_content(self) -> str:
+        return self.decode_case(
+            f"this->{self.field_name} = StringRef(value.data(), value.size());",
+        )
 
     def dump(self, name: str) -> str:
         # Not used since we use dump_field, but required by abstract base class
@@ -1310,14 +1335,13 @@ class PackedBufferTypeInfo(TypeInfo):
         ]
 
     @property
-    def decode_length_content(self) -> str:
+    def decode_content(self) -> str:
         """Store pointer to buffer and calculate count of packed varints."""
-        return f"""case {self.number}: {{
-      this->{self.field_name}_data_ = value.data();
-      this->{self.field_name}_length_ = value.size();
-      this->{self.field_name}_count_ = count_packed_varints(value.data(), value.size());
-      break;
-    }}"""
+        return self.decode_case(
+            f"this->{self.field_name}_data_ = value.data();\n"
+            f"this->{self.field_name}_length_ = value.size();\n"
+            f"this->{self.field_name}_count_ = count_packed_varints(value.data(), value.size());",
+        )
 
     @property
     def encode_content(self) -> str:
@@ -1402,17 +1426,11 @@ class FixedArrayBytesType(TypeInfo):
         ]
 
     @property
-    def decode_length_content(self) -> str:
-        o = f"case {self.number}: {{\n"
-        o += "  const std::string &data_str = value.as_string();\n"
-        o += f"  this->{self.field_name}_len = data_str.size();\n"
-        o += f"  if (this->{self.field_name}_len > {self.array_size}) {{\n"
-        o += f"    this->{self.field_name}_len = {self.array_size};\n"
-        o += "  }\n"
-        o += f"  memcpy(this->{self.field_name}, data_str.data(), this->{self.field_name}_len);\n"
-        o += "  break;\n"
-        o += "}"
-        return o
+    def decode_content(self) -> str:
+        return self.decode_case(
+            f"this->{self.field_name}_len = std::min<size_t>(value.size(), {self.array_size});\n"
+            f"memcpy(this->{self.field_name}, value.data(), this->{self.field_name}_len);",
+        )
 
     @property
     def encode_content(self) -> str:
@@ -1421,9 +1439,13 @@ class FixedArrayBytesType(TypeInfo):
             f"this->{self.field_name}", f"this->{self.field_name}_len", max_len=max_len
         ):
             return result
-        if self.force:
-            return f"ProtoEncode::encode_bytes(pos, {self.number}, this->{self.field_name}, this->{self.field_name}_len, true);"
-        return f"ProtoEncode::encode_bytes(pos, {self.number}, this->{self.field_name}, this->{self.field_name}_len);"
+        return _encode_call(
+            "encode_bytes",
+            str(self.number),
+            f"this->{self.field_name}",
+            f"this->{self.field_name}_len",
+            force=self.force,
+        )
 
     def dump(self, name: str) -> str:
         return f"out.append(format_hex_pretty({name}, {name}_len));"
@@ -1471,7 +1493,7 @@ class UInt32Type(VarintTypeMixin, TypeInfo):
     cpp_type = "uint32_t"
     _varint_max_bits = 32
     default_value = "0"
-    decode_varint = "value"
+    decode_expr = "value.as_varint()"
     encode_func = "encode_uint32"
     wire_type = WireType.VARINT  # Uses wire type 0
 
@@ -1494,13 +1516,21 @@ class UInt32Type(VarintTypeMixin, TypeInfo):
 class EnumType(VarintTypeMixin, TypeInfo):
     _varint_max_bits = 32
 
+    def encode_element(self, number: int, element: str) -> str:
+        return _encode_call(
+            self.encode_func,
+            str(number),
+            f"static_cast<uint32_t>({element})",
+            force=True,
+        )
+
     @property
     def cpp_type(self) -> str:
         return f"enums::{self._field.type_name[1:]}"
 
     @property
-    def decode_varint(self) -> str:
-        return f"static_cast<{self.cpp_type}>(value)"
+    def decode_expr(self) -> str:
+        return f"static_cast<{self.cpp_type}>(value.as_varint())"
 
     default_value = ""
     wire_type = WireType.VARINT  # Uses wire type 0
@@ -1520,9 +1550,9 @@ class EnumType(VarintTypeMixin, TypeInfo):
     @property
     def encode_content(self) -> str:
         value_expr = f"static_cast<uint32_t>(this->{self.field_name})"
-        if self.force:
-            return f"ProtoEncode::{self.encode_func}(pos, {self.number}, {value_expr}, true);"
-        return f"ProtoEncode::{self.encode_func}(pos, {self.number}, {value_expr});"
+        return _encode_call(
+            self.encode_func, str(self.number), value_expr, force=self.force
+        )
 
     def dump(self, name: str) -> str:
         return f"out.append_p(proto_enum_to_string<{self.cpp_type}>({name}));"
@@ -1547,7 +1577,7 @@ class EnumType(VarintTypeMixin, TypeInfo):
 class SFixed32Type(FixedSizeTypeMixin, TypeInfo):
     cpp_type = "int32_t"
     default_value = "0"
-    decode_32bit = "value.as_sfixed32()"
+    decode_expr = "value.as_sfixed32()"
     encode_func = "encode_sfixed32"
     wire_type = WireType.FIXED32  # Uses wire type 5
 
@@ -1573,7 +1603,6 @@ class SFixed32Type(FixedSizeTypeMixin, TypeInfo):
 class SFixed64Type(FixedSizeTypeMixin, TypeInfo):
     cpp_type = "int64_t"
     default_value = "0"
-    decode_64bit = "value.as_sfixed64()"
     encode_func = "encode_sfixed64"
     wire_type = WireType.FIXED64  # Uses wire type 1
 
@@ -1600,7 +1629,7 @@ class SInt32Type(VarintTypeMixin, TypeInfo):
     cpp_type = "int32_t"
     _varint_max_bits = 32  # zigzag encoding keeps it 32-bit
     default_value = "0"
-    decode_varint = "decode_zigzag32(static_cast<uint32_t>(value))"
+    decode_expr = "decode_zigzag32(static_cast<uint32_t>(value.as_varint()))"
     encode_func = "encode_sint32"
     wire_type = WireType.VARINT  # Uses wire type 0
 
@@ -1621,7 +1650,7 @@ class SInt64Type(VarintTypeMixin, TypeInfo):
     cpp_type = "int64_t"
     _varint_max_bits = 64
     default_value = "0"
-    decode_varint = "decode_zigzag64(value)"
+    decode_expr = "decode_zigzag64(value.as_varint())"
     encode_func = "encode_sint64"
     wire_type = WireType.VARINT  # Uses wire type 0
 
@@ -1701,9 +1730,9 @@ def _generate_inline_encode_block(
 
     lines = []
     lines.append(f"auto &sub_msg = {element};")
-    lines.append(f"ProtoEncode::write_raw_byte(pos, {tag});")
+    lines.append(_encode_call("write_raw_byte", str(tag)))
     lines.append("uint8_t *len_pos = pos;")
-    lines.append("ProtoEncode::reserve_byte(pos);")
+    lines.append(_encode_call("reserve_byte"))
 
     # Generate inline field encoding for each sub-message field
     for field in sub_desc.field:
@@ -1774,18 +1803,11 @@ class FixedArrayRepeatedType(TypeInfo):
 
     def _encode_element(self, element: str) -> str:
         """Helper to generate encode statement for a single element."""
-        if isinstance(self._ti, EnumType):
-            return f"ProtoEncode::{self._ti.encode_func}(pos, {self.number}, static_cast<uint32_t>({element}), true);"
-        # Repeated message elements use encode_sub_message (force=true is default)
-        if isinstance(self._ti, MessageType):
-            if _is_inline_encode(self._ti.cpp_type):
-                return _generate_inline_encode_block(
-                    self.number, self._ti.cpp_type, element
-                )
-            return f"ProtoEncode::encode_sub_message(pos, buffer, {self.number}, {element});"
-        return (
-            f"ProtoEncode::{self._ti.encode_func}(pos, {self.number}, {element}, true);"
-        )
+        if isinstance(self._ti, MessageType) and _is_inline_encode(self._ti.cpp_type):
+            return _generate_inline_encode_block(
+                self.number, self._ti.cpp_type, element
+            )
+        return self._ti.encode_element(self.number, element)
 
     @property
     def cpp_type(self) -> str:
@@ -2079,55 +2101,23 @@ class RepeatedTypeInfo(TypeInfo):
         return self._ti.wire_type
 
     @property
-    def decode_varint_content(self) -> str:
-        # Pointer fields don't support decoding
-        if self._use_pointer:
-            return None
-        content = self._ti.decode_varint
-        if content is None:
-            return None
-        return (
-            f"case {self.number}: this->{self.field_name}.push_back({content}); break;"
-        )
+    def decode_expr(self) -> str | None:
+        return self._ti.decode_expr
+
+    def _decode_store(self, expr: str) -> str:
+        return f"this->{self.field_name}.push_back({expr});"
 
     @property
-    def decode_length_content(self) -> str:
+    def decode_content(self) -> str | None:
         # Pointer fields don't support decoding
         if self._use_pointer:
             return None
-        content = self._ti.decode_length
-        if content is None and isinstance(self._ti, MessageType):
-            # Special handling for non-template message decoding
-            return f"case {self.number}: this->{self.field_name}.emplace_back(); value.decode_to_message(this->{self.field_name}.back()); break;"
-        if content is None:
-            return None
-        return (
-            f"case {self.number}: this->{self.field_name}.push_back({content}); break;"
-        )
-
-    @property
-    def decode_32bit_content(self) -> str:
-        # Pointer fields don't support decoding
-        if self._use_pointer:
-            return None
-        content = self._ti.decode_32bit
-        if content is None:
-            return None
-        return (
-            f"case {self.number}: this->{self.field_name}.push_back({content}); break;"
-        )
-
-    @property
-    def decode_64bit_content(self) -> str:
-        # Pointer fields don't support decoding
-        if self._use_pointer:
-            return None
-        content = self._ti.decode_64bit
-        if content is None:
-            return None
-        return (
-            f"case {self.number}: this->{self.field_name}.push_back({content}); break;"
-        )
+        if isinstance(self._ti, MessageType):
+            return self.decode_case(
+                f"this->{self.field_name}.emplace_back();\n"
+                f"value.decode_to_message(this->{self.field_name}.back());"
+            )
+        return super().decode_content
 
     @property
     def _ti_is_bool(self) -> bool:
@@ -2135,15 +2125,7 @@ class RepeatedTypeInfo(TypeInfo):
         return isinstance(self._ti, BoolType)
 
     def _encode_element_call(self, element: str) -> str:
-        """Helper to generate encode call for a single element."""
-        if isinstance(self._ti, EnumType):
-            return f"ProtoEncode::{self._ti.encode_func}(pos, {self.number}, static_cast<uint32_t>({element}), true);"
-        # Repeated message elements use encode_sub_message (force=true is default)
-        if isinstance(self._ti, MessageType):
-            return f"ProtoEncode::encode_sub_message(pos, buffer, {self.number}, {element});"
-        return (
-            f"ProtoEncode::{self._ti.encode_func}(pos, {self.number}, {element}, true);"
-        )
+        return self._ti.encode_element(self.number, element)
 
     @property
     def encode_content(self) -> str:
@@ -2152,7 +2134,7 @@ class RepeatedTypeInfo(TypeInfo):
             # Special handling for const char* elements (when container_no_template contains "const char")
             if "const char" in self._container_no_template:
                 o = f"for (const char *it : *this->{self.field_name}) {{\n"
-                o += f"  ProtoEncode::{self._ti.encode_func}(pos, {self.number}, it, strlen(it), true);\n"
+                o += f"  {_encode_call(self._ti.encode_func, str(self.number), 'it', 'strlen(it)', force=True)}\n"
             else:
                 o = f"for (const auto &it : *this->{self.field_name}) {{\n"
                 o += f"  {self._encode_element_call('it')}\n"
@@ -2538,10 +2520,7 @@ def build_message_type(
 ) -> tuple[str, str, str]:
     public_content: list[str] = []
     protected_content: list[str] = []
-    decode_varint: list[str] = []
-    decode_length: list[str] = []
-    decode_32bit: list[str] = []
-    decode_64bit: list[str] = []
+    decode: list[str] = []
     encode: list[str] = []
     dump: list[str] = []
     size_calc: list[str] = []
@@ -2670,22 +2649,8 @@ def build_message_type(
             if field.options.HasExtension(pb.field_ifdef):
                 field_ifdef = field.options.Extensions[pb.field_ifdef]
 
-            if ti.decode_varint_content:
-                decode_varint.extend(
-                    wrap_with_ifdef(ti.decode_varint_content, field_ifdef)
-                )
-            if ti.decode_length_content:
-                decode_length.extend(
-                    wrap_with_ifdef(ti.decode_length_content, field_ifdef)
-                )
-            if ti.decode_32bit_content:
-                decode_32bit.extend(
-                    wrap_with_ifdef(ti.decode_32bit_content, field_ifdef)
-                )
-            if ti.decode_64bit_content:
-                decode_64bit.extend(
-                    wrap_with_ifdef(ti.decode_64bit_content, field_ifdef)
-                )
+            if case := ti.decode_content:
+                decode.extend(wrap_with_ifdef(case, field_ifdef))
         if ti.dump_content:
             # Check for field_ifdef option for dump as well
             field_ifdef = None
@@ -2695,49 +2660,15 @@ def build_message_type(
             dump.extend(wrap_with_ifdef(ti.dump_content, field_ifdef))
 
     cpp = ""
-    if decode_varint:
-        o = f"bool {desc.name}::decode_varint(uint32_t field_id, proto_varint_value_t value) {{\n"
-        o += "  switch (field_id) {\n"
-        o += indent("\n".join(decode_varint), "    ") + "\n"
-        o += "    default: return false;\n"
+    if decode:
+        o = f"void {desc.name}::decode_field(uint32_t tag, const uint8_t *data, proto_varint_value_t scalar) {{\n"
+        o += "  const ProtoFieldValue value(data, scalar);\n"
+        o += "  switch (tag) {\n"
+        o += indent("\n".join(decode), "    ") + "\n"
         o += "  }\n"
-        o += "  return true;\n"
         o += "}\n"
         cpp += o
-        prot = "bool decode_varint(uint32_t field_id, proto_varint_value_t value) override;"
-        protected_content.insert(0, prot)
-    if decode_length:
-        o = f"bool {desc.name}::decode_length(uint32_t field_id, ProtoLengthDelimited value) {{\n"
-        o += "  switch (field_id) {\n"
-        o += indent("\n".join(decode_length), "    ") + "\n"
-        o += "    default: return false;\n"
-        o += "  }\n"
-        o += "  return true;\n"
-        o += "}\n"
-        cpp += o
-        prot = "bool decode_length(uint32_t field_id, ProtoLengthDelimited value) override;"
-        protected_content.insert(0, prot)
-    if decode_32bit:
-        o = f"bool {desc.name}::decode_32bit(uint32_t field_id, Proto32Bit value) {{\n"
-        o += "  switch (field_id) {\n"
-        o += indent("\n".join(decode_32bit), "    ") + "\n"
-        o += "    default: return false;\n"
-        o += "  }\n"
-        o += "  return true;\n"
-        o += "}\n"
-        cpp += o
-        prot = "bool decode_32bit(uint32_t field_id, Proto32Bit value) override;"
-        protected_content.insert(0, prot)
-    if decode_64bit:
-        o = f"bool {desc.name}::decode_64bit(uint32_t field_id, Proto64Bit value) {{\n"
-        o += "  switch (field_id) {\n"
-        o += indent("\n".join(decode_64bit), "    ") + "\n"
-        o += "    default: return false;\n"
-        o += "  }\n"
-        o += "  return true;\n"
-        o += "}\n"
-        cpp += o
-        prot = "bool decode_64bit(uint32_t field_id, Proto64Bit value) override;"
+        prot = "void decode_field(uint32_t tag, const uint8_t *data, proto_varint_value_t scalar) override;"
         protected_content.insert(0, prot)
 
     # Generate custom decode() override for messages with FixedVector fields
@@ -2784,28 +2715,36 @@ def build_message_type(
             )
             for line in encode
         ]
-        o = f"{speed_attr}uint8_t *{desc.name}::encode(ProtoWriteBuffer &buffer PROTO_ENCODE_DEBUG_PARAM) const {{\n"
+        o = f"{speed_attr}uint8_t *{desc.name}::encode_msg(const void *self, ProtoWriteBuffer &buffer PROTO_ENCODE_DEBUG_PARAM) {{\n"
+        o += f"  const auto &msg = *static_cast<const {desc.name} *>(self);\n"
         o += "  uint8_t *__restrict__ pos = buffer.get_pos();\n"
-        o += indent("\n".join(encode_debug)) + "\n"
+        o += indent("\n".join(encode_debug)).replace("this->", "msg.") + "\n"
         o += "  return pos;\n"
         o += "}\n"
         cpp += o
-        prot = (
-            "uint8_t *encode(ProtoWriteBuffer &buffer PROTO_ENCODE_DEBUG_PARAM) const;"
+        public_content.append(
+            "static uint8_t *encode_msg(const void *self, ProtoWriteBuffer &buffer PROTO_ENCODE_DEBUG_PARAM);"
+        )
+        public_content.append(
+            "uint8_t *encode(ProtoWriteBuffer &buffer PROTO_ENCODE_DEBUG_PARAM) const {\n"
+            "  return encode_msg(this, buffer PROTO_ENCODE_DEBUG_ARG);\n"
+            "}"
         )
-        public_content.append(prot)
     # If no fields to encode or message doesn't need encoding, the default implementation in ProtoMessage will be used
 
     # Add calculate_size method only if this message needs encoding and has fields
     if needs_encode and size_calc and not is_inline_only:
-        o = f"{speed_attr}uint32_t {desc.name}::calculate_size() const {{\n"
+        o = f"{speed_attr}uint32_t {desc.name}::calc_size_msg(const void *self) {{\n"
+        o += f"  const auto &msg = *static_cast<const {desc.name} *>(self);\n"
         o += "  uint32_t size = 0;\n"
-        o += indent("\n".join(size_calc)) + "\n"
+        o += indent("\n".join(size_calc)).replace("this->", "msg.") + "\n"
         o += "  return size;\n"
         o += "}\n"
         cpp += o
-        prot = "uint32_t calculate_size() const;"
-        public_content.append(prot)
+        public_content.append("static uint32_t calc_size_msg(const void *self);")
+        public_content.append(
+            "uint32_t calculate_size() const { return calc_size_msg(this); }"
+        )
     # If no fields to calculate size for or message doesn't need encoding, the default implementation in ProtoMessage will be used
 
     # dump_to method declaration in header

script/git-hooks/post-checkout

@@ -1,27 +1,49 @@
 #!/bin/sh
 # Prepare the dev environment for a new checkout or worktree.
 #
-# Installed into the git hooks directory by script/setup. Deliberately tiny and
-# self-contained: it stays valid on branches where script/setup does not exist,
-# and simply does nothing there.
+# Installed into the git hooks directory by script/setup.py. Deliberately tiny
+# and self-contained: it stays valid on branches where the setup script does not
+# exist, and simply does nothing there.
 
 # $3 is 1 for a branch checkout, 0 for a file checkout.
 [ "$3" = "1" ] || exit 0
 
 top=$(git rev-parse --show-toplevel 2>/dev/null) || exit 0
 
-# This also runs on ordinary branch switches, where there is nothing to do.
+# This also runs on ordinary branch switches, where there is nothing to do. Both
+# layouts are checked because git for Windows runs hooks under its own bundled
+# shell, where the environment lives in venv/Scripts rather than venv/bin.
 [ -x "$top/venv/bin/python" ] && exit 0
-[ -x "$top/script/setup" ] || exit 0
+[ -f "$top/venv/Scripts/python.exe" ] && exit 0
+
+# Branches from before the setup script moved to Python carry only the shell
+# entry point, so whichever one the checked out branch has is used.
+py=
+if [ -f "$top/script/setup.py" ]; then
+  # The interpreter goes by different names across platforms, and on Windows
+  # "python3" is often a stub that opens the app store instead of running
+  # anything, so each candidate is tried before it is used. Doing nothing is the
+  # right outcome when none of them work.
+  for candidate in "python3" "python" "py -3"; do
+    # Unquoted on purpose: the launcher candidate is a command plus a flag.
+    if $candidate -c "" >/dev/null 2>&1; then
+      py=$candidate
+      break
+    fi
+  done
+  [ -n "$py" ] || exit 0
+elif ! [ -x "$top/script/setup" ]; then
+  exit 0
+fi
 
 # Every worktree shares the hooks directory of the checkout it was created
-# from, and the script/setup run below is the one from whichever branch was just
+# from, and the setup script run below is the one from whichever branch was just
 # checked out. Older branches install their own pre-commit hook without checking
 # for a worktree: that moves the shared hook aside as pre-commit.legacy and
 # replaces it with one tied to this worktree's virtual environment, so commits
 # break in every checkout. To rule that out, the hooks directory is copied
-# before script/setup runs and put back exactly as it was afterwards, including
-# removing any file script/setup added.
+# before the setup script runs and put back exactly as it was afterwards,
+# including removing any file the setup script added.
 hooks=$(git rev-parse --path-format=absolute --git-path hooks 2>/dev/null) || exit 0
 snap=$(mktemp -d "$hooks/.post-checkout.XXXXXX") || exit 0
 cp -p "$hooks"/* "$snap"/ 2>/dev/null
@@ -29,7 +51,13 @@ cp -p "$hooks"/* "$snap"/ 2>/dev/null
 # Clear VIRTUAL_ENV so a checkout made from a shell with an environment already
 # activated still gets its own, rather than having the active one repointed at
 # this working tree.
-env -u VIRTUAL_ENV "$top/script/setup"
+unset VIRTUAL_ENV
+if [ -n "$py" ]; then
+  # Unquoted on purpose, as above.
+  $py "$top/script/setup.py"
+else
+  "$top/script/setup"
+fi
 status=$?
 
 for f in "$hooks"/*; do

script/helpers.py

@@ -1104,6 +1104,10 @@ def get_components_per_integration_fixture() -> dict[str, set[str]]:
 
 
 _TEST_FUNC_RE = re.compile(r"async def (test_\w+)")
+# Any usage form (decorator, pytestmark assignment or list element); only
+# test_*.py files are scanned, so the marker docs elsewhere cannot false-hit
+_SHARED_YAML_USE_RE = re.compile(r"\bmark\.shared_yaml")
+_SHARED_YAML_ARG_RE = re.compile(r"\(\s*[\"'](\w+)[\"']\s*\)")
 
 
 @cache
@@ -1123,6 +1127,19 @@ def get_fixture_to_test_files() -> dict[str, frozenset[str]]:
         for func in _TEST_FUNC_RE.findall(content):
             base_name = func.replace("test_", "").partition("[")[0]
             result.setdefault(base_name, set()).add(rel_path)
+        # Shared fixtures are named by marker, not by a test function; each
+        # decorator must carry a string literal or its fixture would silently
+        # map to no tests
+        for use in _SHARED_YAML_USE_RE.finditer(content):
+            arg = _SHARED_YAML_ARG_RE.match(content, use.end())
+            if arg is None:
+                line = content.count("\n", 0, use.start()) + 1
+                raise ValueError(
+                    f"{rel_path}:{line}: shared_yaml marker must take a "
+                    "single-line string literal so CI test selection can map "
+                    "its fixture"
+                )
+            result.setdefault(arg.group(1), set()).add(rel_path)
 
     return {k: frozenset(v) for k, v in result.items()}
 

script/setup

@@ -1,71 +1,7 @@
 #!/usr/bin/env bash
-# Set up ESPHome dev environment
+# Set up ESPHome dev environment.
+#
+# The work is done by setup.py, which script/setup.bat also runs, so the Unix
+# and Windows entry points share one implementation.
 
-set -e
-
-cd "$(dirname "$0")/.."
-if [ -n "$VIRTUAL_ENV" ]; then
-  # A virtual environment is already active (e.g. the devcontainer's pre-provisioned
-  # esphome-venv). Install into it rather than creating a ./venv in the workspace.
-  venv_state=active
-elif [ -x venv/bin/python ]; then
-  # Reuse the environment from an earlier run, so this script can be run again
-  # at any time to pick up dependency changes.
-  venv_state=reused
-  source venv/bin/activate
-else
-  venv_state=created
-  # --clear replaces a partial environment left behind by an interrupted run.
-  if [ -x "$(command -v uv)" ]; then
-    uv venv --clear --seed venv
-  else
-    python3 -m venv --clear venv
-  fi
-  source venv/bin/activate
-fi
-
-if ! [ -x "$(command -v uv)" ]; then
-  python3 -m pip install uv
-fi
-
-uv pip install setuptools wheel
-uv pip install -e ".[dev,test]" --config-settings editable_mode=compat
-
-# A worktree shares one git hooks directory with the main checkout it was
-# created from, so hooks are installed from the main checkout only. Installing
-# from a worktree would point the shared hook at that worktree's virtual
-# environment, breaking it for everyone once the worktree is removed.
-git_dir="$(git rev-parse --absolute-git-dir 2>/dev/null || true)"
-common_dir="$(git rev-parse --path-format=absolute --git-common-dir 2>/dev/null || true)"
-if [ -n "$common_dir" ] && [ "$git_dir" = "$common_dir" ]; then
-  # --overwrite replaces any hook already in place. Without it, prek finds a
-  # previously installed pre-commit hook, moves it aside to
-  # .git/hooks/pre-commit.legacy and keeps calling it, so every commit would
-  # run both tools.
-  prek install --overwrite
-
-  # Prepares the virtual environment for new checkouts and worktrees. Installed
-  # once here, it covers every worktree created from this checkout.
-  if [ -d "$common_dir/hooks" ]; then
-    cp script/git-hooks/post-checkout "$common_dir/hooks/post-checkout"
-    chmod +x "$common_dir/hooks/post-checkout"
-  fi
-fi
-
-mkdir -p .temp
-
-echo
-echo
-case "$venv_state" in
-  created)
-    echo "Virtual environment created at ./venv. Run 'source venv/bin/activate' to use it."
-    ;;
-  reused)
-    echo "Dependencies updated in the existing ./venv. Run 'source venv/bin/activate' to use it."
-    ;;
-  active)
-    echo "Dependencies installed into the active virtual environment:"
-    echo "  $VIRTUAL_ENV"
-    echo "It is already active in this shell, so no 'source venv/bin/activate' is needed."
-    ;;
-esac
+exec python3 "$(dirname "$0")/setup.py" "$@"

script/setup.bat

@@ -1,28 +1 @@
-@echo off
-
-if defined VIRTUAL_ENV goto :install
-
-echo Starting the Virtual Environment
-python -m venv venv
-call venv/Scripts/activate
-echo Running the Virtual Environment
-
-:install
-
-echo Installing required packages...
-
-python.exe -m pip install --upgrade pip
-
-pip3 install -r requirements.txt -r requirements_test.txt -r requirements_dev.txt
-pip3 install setuptools wheel
-pip3 install -e ".[dev,test]" --config-settings editable_mode=compat
-
-rem --overwrite replaces any hook already in place. Without it, prek finds a
-rem previously installed pre-commit hook, moves it aside to
-rem .git/hooks/pre-commit.legacy and keeps calling it, so every commit would
-rem run both tools.
-prek install --overwrite
-
-echo .
-echo .
-echo Virtual environment created. Run 'venv/Scripts/activate' to use it.
+@python "%~dp0setup.py" %*

script/setup.py

@@ -0,0 +1,222 @@
+#!/usr/bin/env python3
+"""Set up the ESPHome development environment.
+
+Shared implementation behind script/setup and script/setup.bat, so the Unix and
+Windows entry points cannot drift apart. Uses only the standard library: it runs
+before any dependency has been installed.
+"""
+
+import os
+from pathlib import Path
+import shutil
+import subprocess
+import sys
+import sysconfig
+
+MIN_PYTHON = (3, 12)
+
+ROOT = Path(__file__).resolve().parent.parent
+DEFAULT_VENV = ROOT / "venv"
+POST_CHECKOUT_HOOK = ROOT / "script" / "git-hooks" / "post-checkout"
+
+# State of the environment the dependencies end up in, used for the closing
+# message.
+VENV_ACTIVE = "active"
+VENV_REUSED = "reused"
+VENV_CREATED = "created"
+
+
+def bin_dir(venv: Path) -> Path:
+    """Return the directory holding a virtual environment's executables.
+
+    The "venv" scheme resolves to bin on Unix and Scripts on Windows, so the
+    layout does not have to be hardcoded here.
+    """
+    base = str(venv)
+    return Path(
+        sysconfig.get_path("scripts", "venv", vars={"base": base, "platbase": base})
+    )
+
+
+def venv_python(venv: Path) -> Path:
+    """Return the path to a virtual environment's interpreter."""
+    name = "python.exe" if os.name == "nt" else "python"
+    return bin_dir(venv) / name
+
+
+def run(command: list[str], env: dict[str, str] | None = None) -> None:
+    """Run a command, aborting the whole script if it fails."""
+    print(f"+ {' '.join(command)}", flush=True)
+    result = subprocess.run(command, cwd=ROOT, env=env, check=False)
+    if result.returncode != 0:
+        # Some tools fail without printing anything, so name the step that broke.
+        print(
+            f"Failed with exit code {result.returncode}: {command[0]}", file=sys.stderr
+        )
+        raise SystemExit(result.returncode)
+
+
+def git_output(*args: str) -> str:
+    """Return the trimmed output of a git command, or "" if it cannot be run."""
+    try:
+        result = subprocess.run(
+            ["git", *args], cwd=ROOT, capture_output=True, text=True, check=False
+        )
+    except OSError:
+        # Git is not required to install the dependencies, only to install hooks.
+        return ""
+    if result.returncode != 0:
+        return ""
+    return result.stdout.strip()
+
+
+def create_venv(venv: Path) -> None:
+    """Create a virtual environment, replacing anything already at the path."""
+    # --clear replaces a partial environment left behind by an interrupted run.
+    if (uv := shutil.which("uv")) is not None:
+        run([uv, "venv", "--clear", "--seed", str(venv)])
+    else:
+        run([sys.executable, "-m", "venv", "--clear", str(venv)])
+
+
+def venv_environment(venv: Path) -> dict[str, str]:
+    """Return the environment child processes need to target a virtual env.
+
+    Equivalent to sourcing the environment's activate script: tools such as uv
+    and prek pick the environment up from VIRTUAL_ENV and PATH.
+    """
+    env = dict(os.environ)
+    env["VIRTUAL_ENV"] = str(venv)
+    env.pop("PYTHONHOME", None)
+    path = str(bin_dir(venv))
+    # An empty entry would be appended if PATH is unset, and on Unix that means
+    # the working directory is searched for executables.
+    if existing := env.get("PATH"):
+        path = os.pathsep.join([path, existing])
+    env["PATH"] = path
+    return env
+
+
+def find_uv(venv: Path, env: dict[str, str]) -> str:
+    """Return the path to uv, installing it into the environment if needed."""
+    if (uv := shutil.which("uv", path=env["PATH"])) is not None:
+        return uv
+    run([str(venv_python(venv)), "-m", "pip", "install", "uv"], env=env)
+    if (uv := shutil.which("uv", path=env["PATH"])) is not None:
+        return uv
+    raise SystemExit("uv could not be installed, aborting.")
+
+
+def install_dependencies(venv: Path, env: dict[str, str]) -> None:
+    """Install ESPHome and its development dependencies into the environment."""
+    uv = find_uv(venv, env)
+    run([uv, "pip", "install", "setuptools", "wheel"], env=env)
+    # The dev and test extras pull in requirements_dev.txt and
+    # requirements_test.txt, and the package itself pulls in requirements.txt,
+    # so this single install covers every requirements file.
+    run(
+        [
+            uv,
+            "pip",
+            "install",
+            "-e",
+            ".[dev,test]",
+            "--config-settings",
+            "editable_mode=compat",
+        ],
+        env=env,
+    )
+
+
+def install_git_hooks(env: dict[str, str]) -> None:
+    """Install the git hooks, but only when run from the main checkout.
+
+    A worktree shares one git hooks directory with the main checkout it was
+    created from. Installing from a worktree would point the shared hook at that
+    worktree's virtual environment, breaking it for everyone once the worktree is
+    removed.
+    """
+    git_dir = git_output("rev-parse", "--absolute-git-dir")
+    common_dir = git_output("rev-parse", "--path-format=absolute", "--git-common-dir")
+    if not git_dir or not common_dir or Path(git_dir) != Path(common_dir):
+        return
+
+    prek = shutil.which("prek", path=env["PATH"])
+    if prek is None:
+        raise SystemExit("prek was not installed, aborting.")
+    # --overwrite replaces any hook already in place. Without it, prek finds a
+    # previously installed pre-commit hook, moves it aside to
+    # .git/hooks/pre-commit.legacy and keeps calling it, so every commit would
+    # run both tools.
+    run([prek, "install", "--overwrite"], env=env)
+
+    # Prepares the virtual environment for new checkouts and worktrees. Installed
+    # once here, it covers every worktree created from this checkout.
+    hooks_dir = Path(common_dir) / "hooks"
+    if hooks_dir.is_dir():
+        installed = hooks_dir / "post-checkout"
+        shutil.copyfile(POST_CHECKOUT_HOOK, installed)
+        installed.chmod(0o755)
+
+
+def activate_hint() -> str:
+    """Return the command that activates the environment this script creates."""
+    activate = bin_dir(DEFAULT_VENV).relative_to(ROOT) / "activate"
+    if os.name == "nt":
+        return str(activate)
+    return f"source {activate.as_posix()}"
+
+
+def report(state: str, venv: Path) -> None:
+    """Print the closing message for the environment that was set up."""
+    location = f"./{DEFAULT_VENV.name}"
+    print()
+    print()
+    if state == VENV_ACTIVE:
+        print("Dependencies installed into the active virtual environment:")
+        print(f"  {venv}")
+        print(
+            f"It is already active in this shell, so no '{activate_hint()}' is needed."
+        )
+    elif state == VENV_REUSED:
+        print(
+            f"Dependencies updated in the existing {location}. "
+            f"Run '{activate_hint()}' to use it."
+        )
+    else:
+        print(
+            f"Virtual environment created at {location}. "
+            f"Run '{activate_hint()}' to use it."
+        )
+
+
+def main() -> None:
+    """Set up the development environment."""
+    if sys.version_info < MIN_PYTHON:
+        raise SystemExit(
+            f"ESPHome needs Python {MIN_PYTHON[0]}.{MIN_PYTHON[1]} or newer, "
+            f"but this is Python {sys.version.split()[0]}."
+        )
+
+    # A virtual environment that is already active (for example the
+    # devcontainer's pre-provisioned esphome-venv) is installed into rather than
+    # creating a ./venv in the workspace.
+    if active := os.environ.get("VIRTUAL_ENV"):
+        state, venv = VENV_ACTIVE, Path(active)
+    elif venv_python(DEFAULT_VENV).is_file():
+        # Reuse the environment from an earlier run, so this script can be run
+        # again at any time to pick up dependency changes.
+        state, venv = VENV_REUSED, DEFAULT_VENV
+    else:
+        state, venv = VENV_CREATED, DEFAULT_VENV
+        create_venv(venv)
+
+    env = venv_environment(venv)
+    install_dependencies(venv, env)
+    install_git_hooks(env)
+    (ROOT / ".temp").mkdir(exist_ok=True)
+    report(state, venv)
+
+
+if __name__ == "__main__":
+    main()

sdkconfig.defaults

@@ -17,6 +17,8 @@ CONFIG_ESP_TASK_WDT_INIT=y
 CONFIG_ESP_TASK_WDT_PANIC=y
 CONFIG_ESP_TASK_WDT_CHECK_IDLE_TASK_CPU0=n
 CONFIG_ESP_TASK_WDT_CHECK_IDLE_TASK_CPU1=n
+CONFIG_FREERTOS_USE_TICKLESS_IDLE=y
+CONFIG_PM_ENABLE=y
 
 # esp32_ble
 CONFIG_BT_ENABLED=y

tests/benchmarks/components/api/bench_proto_proxy.cpp

@@ -249,7 +249,7 @@ static APIBuffer build_infrared_rf_transmit_wire() {
   std::memcpy(bytes + len, packed, packed_len);
   len += packed_len;
   // field 6: modulation = 1 (non-zero so it's actually emitted and exercises
-  // decode_varint for this field, matching the documented layout above).
+  // decode_field for this field, matching the documented layout above).
   put_byte(0x30);
   put_varint(1);
 

tests/benchmarks/stubs/esphome/components/serial_proxy/serial_proxy.h

@@ -40,6 +40,9 @@ class SerialProxy {
     return SerialProxyResult::SERIAL_PROXY_RESULT_OK;
   }
   void write_from_client(api::APIConnection *api_connection, const uint8_t *data, size_t len) {}
+  SerialProxyResult set_mode_from_client(api::APIConnection *api_connection, api::enums::SerialProxyMode mode) {
+    return SerialProxyResult::SERIAL_PROXY_RESULT_OK;
+  }
   SerialProxyResult set_modem_pins(api::APIConnection *api_connection, uint32_t line_states) {
     return SerialProxyResult::SERIAL_PROXY_RESULT_OK;
   }

tests/component_tests/sendspin/config/device_info_default.yaml

@@ -0,0 +1,12 @@
+esphome:
+  name: test
+
+esp32:
+  board: esp32dev
+  framework:
+    type: esp-idf
+
+wifi:
+  ap:
+
+sendspin:

tests/component_tests/sendspin/config/device_info_explicit.yaml

@@ -0,0 +1,18 @@
+esphome:
+  name: test
+  project:
+    name: project_manufacturer.project_model
+    version: 9.9.9
+
+esp32:
+  board: esp32dev
+  framework:
+    type: esp-idf
+
+wifi:
+  ap:
+
+sendspin:
+  manufacturer: Explicit Manufacturer
+  model: Explicit Model
+  firmware_version: 1.2.3

tests/component_tests/sendspin/config/device_info_project.yaml

@@ -0,0 +1,15 @@
+esphome:
+  name: test
+  project:
+    name: project_manufacturer.project_model
+    version: 9.9.9
+
+esp32:
+  board: esp32dev
+  framework:
+    type: esp-idf
+
+wifi:
+  ap:
+
+sendspin:

tests/component_tests/sendspin/test_device_info.py

@@ -0,0 +1,83 @@
+"""Tests for the device information the sendspin hub reports to the server."""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from pathlib import Path
+
+import pytest
+
+from esphome import config_validation as cv
+from esphome.components.sendspin import (
+    CONF_FIRMWARE_VERSION,
+    CONF_MANUFACTURER,
+    CONFIG_SCHEMA,
+)
+from esphome.const import CONF_MODEL, PlatformFramework
+from tests.component_tests.types import SetCoreConfigCallable
+
+
+def test_explicit_device_info_wins_over_project(
+    generate_main: Callable[[str | Path], str],
+    component_config_path: Callable[[str], Path],
+) -> None:
+    """Configured values take precedence over the project information."""
+    main_cpp = generate_main(component_config_path("device_info_explicit.yaml"))
+
+    assert 'set_manufacturer("Explicit Manufacturer")' in main_cpp
+    assert 'set_model("Explicit Model")' in main_cpp
+    assert 'set_firmware_version("1.2.3")' in main_cpp
+
+
+def test_project_supplies_device_info(
+    generate_main: Callable[[str | Path], str],
+    component_config_path: Callable[[str], Path],
+) -> None:
+    """Without configured values, the project name splits into manufacturer and model."""
+    main_cpp = generate_main(component_config_path("device_info_project.yaml"))
+
+    assert 'set_manufacturer("project_manufacturer")' in main_cpp
+    assert 'set_model("project_model")' in main_cpp
+    assert 'set_firmware_version("9.9.9")' in main_cpp
+
+
+def test_no_device_info_leaves_hub_defaults(
+    generate_main: Callable[[str | Path], str],
+    component_config_path: Callable[[str], Path],
+) -> None:
+    """With neither source, nothing is emitted and the hub keeps its own defaults."""
+    main_cpp = generate_main(component_config_path("device_info_default.yaml"))
+
+    assert "set_manufacturer(" not in main_cpp
+    assert "set_model(" not in main_cpp
+    assert "set_firmware_version(" not in main_cpp
+
+
+@pytest.mark.parametrize(
+    "conf_key", [CONF_MANUFACTURER, CONF_MODEL, CONF_FIRMWARE_VERSION]
+)
+def test_empty_device_info_rejected(
+    set_core_config: SetCoreConfigCallable, conf_key: str
+) -> None:
+    """An empty string would be sent to the server as an empty value, so it is not accepted."""
+    set_core_config(PlatformFramework.ESP32_IDF)
+
+    with pytest.raises(cv.Invalid):
+        CONFIG_SCHEMA({conf_key: ""})
+
+
+@pytest.mark.parametrize(
+    "conf_key", [CONF_MANUFACTURER, CONF_MODEL, CONF_FIRMWARE_VERSION]
+)
+def test_device_info_capped_at_127_bytes(
+    set_core_config: SetCoreConfigCallable, conf_key: str
+) -> None:
+    """The cap is in bytes so the protobuf length prefix stays a single byte."""
+    set_core_config(PlatformFramework.ESP32_IDF)
+
+    CONFIG_SCHEMA({conf_key: "a" * 127})
+    with pytest.raises(cv.Invalid):
+        CONFIG_SCHEMA({conf_key: "a" * 128})
+    # 64 two-byte characters is 128 bytes.
+    with pytest.raises(cv.Invalid):
+        CONFIG_SCHEMA({conf_key: "é" * 64})

tests/component_tests/sendspin/test_media_source.py

@@ -0,0 +1,90 @@
+"""Validation tests for the sendspin media_source platform.
+
+These cover the codec preference list, whose rejection branches a compile test
+cannot reach: a `test*.yaml` can only assert that a configuration is accepted.
+"""
+
+from typing import Any
+
+import pytest
+
+from esphome import config_validation as cv
+from esphome.components.sendspin import CONF_CODECS, _get_data
+from esphome.components.sendspin.media_source import CONFIG_SCHEMA
+from esphome.const import PlatformFramework
+from esphome.types import ConfigType
+from tests.component_tests.types import SetCoreConfigCallable
+
+
+def _media_source_config(**overrides: Any) -> ConfigType:
+    """Build a minimal valid media source config, allowing field overrides."""
+    config: ConfigType = {
+        "id": "sendspin_media_source",
+        "sendspin_id": "sendspin_hub",
+    }
+    config.update(overrides)
+    return config
+
+
+def test_default_codecs_at_48_khz(set_core_config: SetCoreConfigCallable) -> None:
+    """Every codec is advertised when the sample rate suits all of them."""
+    set_core_config(PlatformFramework.ESP32_IDF)
+
+    config = CONFIG_SCHEMA(_media_source_config())
+
+    assert config[CONF_CODECS] == ["flac", "opus", "pcm"]
+
+
+def test_default_codecs_drop_opus_at_other_rates(
+    set_core_config: SetCoreConfigCallable,
+) -> None:
+    """Opus only supports 48 kHz, so it leaves the default list at other rates."""
+    set_core_config(PlatformFramework.ESP32_IDF)
+
+    config = CONFIG_SCHEMA(_media_source_config(sample_rate=44100))
+
+    assert config[CONF_CODECS] == ["flac", "pcm"]
+
+
+def test_configured_order_is_preserved(set_core_config: SetCoreConfigCallable) -> None:
+    """The list is a preference order, so it reaches the player role as written."""
+    set_core_config(PlatformFramework.ESP32_IDF)
+
+    CONFIG_SCHEMA(_media_source_config(codecs=["pcm", "flac"]))
+
+    assert _get_data().player_config[CONF_CODECS] == ["pcm", "flac"]
+
+
+def test_empty_codec_list_rejected(set_core_config: SetCoreConfigCallable) -> None:
+    """A player with no codecs at all could never be given a stream."""
+    set_core_config(PlatformFramework.ESP32_IDF)
+
+    with pytest.raises(cv.Invalid, match="length of value must be at least 1"):
+        CONFIG_SCHEMA(_media_source_config(codecs=[]))
+
+
+def test_duplicate_codec_rejected(set_core_config: SetCoreConfigCallable) -> None:
+    """A repeated codec has no meaning in a preference order."""
+    set_core_config(PlatformFramework.ESP32_IDF)
+
+    with pytest.raises(cv.Invalid, match="may only be listed once"):
+        CONFIG_SCHEMA(_media_source_config(codecs=["flac", "flac"]))
+
+
+def test_unknown_codec_rejected(set_core_config: SetCoreConfigCallable) -> None:
+    """Only codecs the player role can decode are accepted."""
+    set_core_config(PlatformFramework.ESP32_IDF)
+
+    with pytest.raises(cv.Invalid, match="Unknown value"):
+        CONFIG_SCHEMA(_media_source_config(codecs=["mp3"]))
+
+
+def test_opus_at_wrong_sample_rate_rejected(
+    set_core_config: SetCoreConfigCallable,
+) -> None:
+    """Asking for Opus at a rate it cannot handle fails rather than silently
+    dropping the stated preference."""
+    set_core_config(PlatformFramework.ESP32_IDF)
+
+    with pytest.raises(cv.Invalid, match="requires a sample_rate of 48000"):
+        CONFIG_SCHEMA(_media_source_config(codecs=["opus"], sample_rate=44100))

tests/component_tests/template/test_template_visibility.py

@@ -0,0 +1,76 @@
+"""The template platforms surface value-describing metadata on the main form.
+
+Hardware platforms get sensible defaults for unit/device_class/etc., so those
+fields fall through to the editor's advanced disclosure. A ``template`` entity
+has no such defaults -- the user is expected to define them -- so the template
+platforms pass ``visibility=cv.Visibility.UI`` to promote them onto the form.
+"""
+
+from __future__ import annotations
+
+import importlib
+
+import pytest
+
+import esphome.config_validation as cv
+
+
+def _markers(schema: cv.Schema) -> dict[str, object]:
+    s = schema
+    if hasattr(s, "validators"):
+        # cv.All -> the schema is the first validator.
+        s = s.validators[0]
+    return {str(k): k for k in s.schema}
+
+
+@pytest.mark.parametrize(
+    ("platform", "fields"),
+    [
+        (
+            "sensor",
+            [
+                "unit_of_measurement",
+                "accuracy_decimals",
+                "device_class",
+                "state_class",
+                "force_update",
+            ],
+        ),
+        ("binary_sensor", ["device_class"]),
+        ("switch", ["device_class"]),
+        ("cover", ["device_class"]),
+        ("button", ["device_class"]),
+        ("valve", ["device_class"]),
+        ("event", ["device_class"]),
+        ("text_sensor", ["device_class"]),
+        ("number", ["device_class", "unit_of_measurement"]),
+    ],
+)
+def test_template_metadata_is_ui(platform: str, fields: list[str]) -> None:
+    mod = importlib.import_module(f"esphome.components.template.{platform}")
+    markers = _markers(mod.CONFIG_SCHEMA)
+    for field in fields:
+        assert markers[field].visibility is cv.Visibility.UI, f"{platform}.{field}"
+
+
+def test_template_sensor_promotion_preserves_defaults() -> None:
+    """Promoting to UI must not drop the fields' defaults."""
+    from esphome.components.template.sensor import CONFIG_SCHEMA
+
+    markers = _markers(CONFIG_SCHEMA)
+    assert markers["accuracy_decimals"].default() == 1
+    assert markers["force_update"].default() is False
+
+
+def test_hardware_platform_metadata_not_promoted() -> None:
+    """Without ``visibility=`` the builders leave metadata unset.
+
+    Unset markers fall through to the consumer's ``Optional`` default of
+    advanced, so hardware platforms are unaffected by the template promotion.
+    """
+    from esphome.components import binary_sensor, sensor
+
+    hw_sensor = _markers(sensor.sensor_schema(device_class="temperature"))
+    assert hw_sensor["device_class"].visibility is None
+    hw_bs = _markers(binary_sensor.binary_sensor_schema(device_class="motion"))
+    assert hw_bs["device_class"].visibility is None

tests/components/api/test_proto_mac_varint.cpp

@@ -59,7 +59,7 @@ static void verify_mac(uint64_t mac, size_t expected_bytes) {
 #ifdef ESPHOME_DEBUG_API
   uint8_t *proto_debug_end_ = api_buf.data() + api_buf.size();
 #endif
-  ProtoEncode::encode_varint_raw_48bit(pos PROTO_ENCODE_DEBUG_ARG, mac);
+  pos = ProtoEncode::encode_varint_raw_48bit(pos PROTO_ENCODE_DEBUG_ARG, mac);
   size_t new_len = pos - api_buf.data();
 
   EXPECT_EQ(new_len, expected_bytes) << "mac=0x" << std::hex << mac << std::dec;

tests/components/core/test_string_ref.cpp

@@ -59,4 +59,47 @@ TEST(StringRefStartsWith, RefOverloadComparesOnlyTheViewedLength) {
   EXPECT_TRUE(ref.starts_with(prefix));
 }
 
+// The generated api messages start their encode only string fields as a null pointer with zero
+// length; every member must treat that exactly like the default constructed empty string.
+TEST(StringRefNullEmpty, BehavesAsEmptyString) {
+  const StringRef null_empty{nullptr, 0};
+  const StringRef empty;
+  EXPECT_TRUE(null_empty.empty());
+  EXPECT_EQ(null_empty.size(), 0u);
+  EXPECT_EQ(null_empty.c_str(), nullptr);
+  EXPECT_TRUE(null_empty == empty);
+  EXPECT_TRUE(null_empty == "");
+  EXPECT_TRUE(null_empty == std::string());
+  EXPECT_EQ(null_empty.compare(empty), 0);
+  EXPECT_EQ(null_empty.compare(""), 0);
+  EXPECT_LT(null_empty.compare("a"), 0);
+  EXPECT_TRUE(null_empty.starts_with(""));
+  EXPECT_FALSE(null_empty.starts_with("a"));
+  EXPECT_EQ(null_empty.str(), std::string());
+  EXPECT_EQ(null_empty.substr(0), std::string());
+  EXPECT_EQ(null_empty.find('a'), std::string::npos);
+  EXPECT_EQ(null_empty.find("a"), std::string::npos);
+  char buf[4] = "xyz";
+  EXPECT_EQ(null_empty.copy(buf, sizeof(buf)), 0u);
+  EXPECT_EQ(null_empty.begin(), null_empty.end());
+}
+
+TEST(StringRefNullEmpty, ComparesAgainstText) {
+  const StringRef null_empty{nullptr, 0};
+  const StringRef text("abc", 3);
+  EXPECT_FALSE(null_empty == text);
+  EXPECT_FALSE(text == null_empty);
+  EXPECT_LT(null_empty.compare(text), 0);
+  EXPECT_GT(text.compare(null_empty), 0);
+  EXPECT_TRUE(text.starts_with(null_empty));
+}
+
+TEST(StringRefNullEmpty, TwoNullViewsAreEqual) {
+  const StringRef a{nullptr, 0};
+  const StringRef b{nullptr, 0};
+  EXPECT_TRUE(a == b);
+  EXPECT_EQ(a.compare(b), 0);
+  EXPECT_TRUE(a.starts_with(b));
+}
+
 }  // namespace esphome::core::testing

tests/components/sendspin/common-hub.yaml

@@ -4,3 +4,6 @@ psram:
 sendspin:
   id: sendspin_hub_id
   task_stack_in_psram: true
+  manufacturer: Test Manufacturer
+  model: Test Model
+  firmware_version: 1.2.3

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

@@ -0,0 +1,14 @@
+substitutions:
+  tx_pin: GPIO4
+  rx_pin: GPIO5
+
+# Compile the tap code paths; no tap is attached, so this exercises the
+# null-tap branches that a normal build never defines.
+esphome:
+  platformio_options:
+    build_flags:
+      - "-DUSE_SERIAL_PROXY_TAP"
+
+packages:
+  uart: !include ../../test_build_components/common/uart/esp32-idf.yaml
+  serial_proxy: !include common.yaml

tests/integration/README.md

@@ -21,6 +21,13 @@ The `yaml_config` fixture automatically loads YAML configurations based on the t
 - The fixture file must exist or the test will fail with a clear error message
 - The fixture automatically injects a dynamic port number into the API configuration
 
+Tests marked `@pytest.mark.shared_yaml("name")` load `fixtures/name.yaml` instead
+of the test-named file and compile it in a shared, hash-keyed build directory, so
+the whole group pays one full compile and each test only a relink. The marker
+argument must be a single-line string literal (CI test selection maps fixtures to
+test files by scanning for it), and marked tests must hand the `yaml_config`
+content to `run_compiled` unmodified.
+
 ### Key Fixtures
 
 - `run_compiled` - Combines write, compile, and run operations into a single context manager

tests/integration/conftest.py

@@ -4,17 +4,22 @@ from __future__ import annotations
 
 import asyncio
 from collections.abc import AsyncGenerator, Callable, Generator
-from contextlib import AbstractAsyncContextManager, asynccontextmanager
+from contextlib import AbstractAsyncContextManager, asynccontextmanager, suppress
 import fcntl
+from functools import cache
+import hashlib
 import logging
 import os
 from pathlib import Path
 import platform
+import re
+import shutil
 import signal
 import socket
 import subprocess
 import sys
 import tempfile
+import time
 from typing import TextIO
 
 from aioesphomeapi import APIClient, APIConnectionError, LogParser, ReconnectLogic
@@ -23,7 +28,13 @@ import pytest_asyncio
 
 import esphome.config
 from esphome.core import CORE
-from esphome.helpers import get_usable_cpu_count
+from esphome.helpers import (
+    get_usable_cpu_count,
+    read_file,
+    rmtree,
+    write_file,
+    write_file_if_changed,
+)
 from esphome.platformio.toolchain import get_idedata
 
 from .const import (
@@ -56,6 +67,21 @@ import pty  # not available on Windows
 pytest.register_assert_rewrite("tests.integration.entity_utils")
 
 
+def pytest_configure(config: pytest.Config) -> None:
+    config.addinivalue_line(
+        "markers",
+        "shared_yaml(name): load fixtures/<name>.yaml and compile it in a shared, "
+        "hash-keyed incremental build directory",
+    )
+
+
+FIXTURES_DIR = Path(__file__).parent / "fixtures"
+REPO_ROOT = Path(__file__).resolve().parent.parent.parent
+
+# CI caches parts of this path; keep in sync with ci.yml integration-tests.
+INTEGRATION_TESTS_ROOT = Path.home() / ".esphome-integration-tests"
+
+
 def _get_platformio_env(cache_dir: Path) -> dict[str, str]:
     """Get environment variables for PlatformIO with shared cache."""
     env = os.environ.copy()
@@ -78,7 +104,7 @@ def _get_platformio_env(cache_dir: Path) -> dict[str, str]:
         )
     # Compile with THIS tree's esphome sources, not wherever the venv's editable
     # install points (which may be a different git worktree or checkout).
-    repo_root = str(Path(__file__).resolve().parent.parent.parent)
+    repo_root = str(REPO_ROOT)
     existing = env.get("PYTHONPATH")
     env["PYTHONPATH"] = f"{repo_root}{os.pathsep}{existing}" if existing else repo_root
     return env
@@ -88,8 +114,7 @@ def _get_platformio_env(cache_dir: Path) -> dict[str, str]:
 def shared_platformio_cache() -> Generator[Path]:
     """Initialize a shared PlatformIO cache for all integration tests."""
     # Use a dedicated directory for integration tests to avoid conflicts.
-    # CI caches parts of this path; keep in sync with ci.yml integration-tests.
-    test_cache_dir = Path.home() / ".esphome-integration-tests"
+    test_cache_dir = INTEGRATION_TESTS_ROOT
     cache_dir = test_cache_dir / "platformio"
 
     # Use a lock file in the home directory to ensure only one process initializes the cache
@@ -112,7 +137,9 @@ def shared_platformio_cache() -> Generator[Path]:
                 init_dir = Path(tmpdir)
                 fixture_path = Path(__file__).parent / "fixtures" / "cache_init.yaml"
                 config_path = init_dir / "cache_init.yaml"
-                config_path.write_text(fixture_path.read_text())
+                config_path.write_text(
+                    fixture_path.read_text(encoding="utf-8"), encoding="utf-8"
+                )
 
                 # Run compilation to populate the cache
                 # We must succeed here to avoid race conditions where multiple
@@ -162,13 +189,6 @@ def integration_test_dir() -> Generator[Path]:
         yield Path(tmpdir)
 
 
-@pytest.fixture
-def isolated_preferences(monkeypatch: pytest.MonkeyPatch, tmp_path: Path) -> None:
-    """Host preferences persist per device name; give the test its own so a
-    provisioned key never leaks into another run."""
-    monkeypatch.setenv("ESPHOME_PREFDIR", str(tmp_path / "prefs"))
-
-
 @pytest.fixture
 def reserved_tcp_port() -> Generator[tuple[int, socket.socket]]:
     """Reserve an unused TCP port by holding the socket open."""
@@ -188,21 +208,29 @@ def unused_tcp_port(reserved_tcp_port: tuple[int, socket.socket]) -> int:
     return reserved_tcp_port[0]
 
 
+@pytest.fixture(autouse=True)
+def isolated_preferences(monkeypatch: pytest.MonkeyPatch, tmp_path: Path) -> Path:
+    """Give every test its own host prefs dir; prefs are keyed only by device
+    name, which tests sharing a fixture also share."""
+    prefdir = tmp_path / "prefs"
+    monkeypatch.setenv("ESPHOME_PREFDIR", str(prefdir))
+    return prefdir
+
+
 @pytest_asyncio.fixture
 async def yaml_config(request: pytest.FixtureRequest, unused_tcp_port: int) -> str:
     """Load YAML configuration based on test name."""
-    # Get the test function name
-    test_name: str = request.node.name
-    # Extract the base test name (remove test_ prefix and any parametrization)
-    base_name = test_name.replace("test_", "").partition("[")[0]
+    shared_name = _shared_yaml_name(request)
+    # Base test name: test_ prefix and any parametrization stripped
+    base_name = shared_name or request.node.name.replace("test_", "").partition("[")[0]
 
     # Load the fixture file
-    fixture_path = Path(__file__).parent / "fixtures" / f"{base_name}.yaml"
+    fixture_path = FIXTURES_DIR / f"{base_name}.yaml"
     if not fixture_path.exists():
         raise FileNotFoundError(f"Fixture file not found: {fixture_path}")
 
     loop = asyncio.get_running_loop()
-    content = await loop.run_in_executor(None, fixture_path.read_text)
+    content = await loop.run_in_executor(None, read_file, fixture_path)
 
     # Replace the port in the config if it contains api section
     if "api:" in content:
@@ -226,11 +254,13 @@ async def yaml_config(request: pytest.FixtureRequest, unused_tcp_port: int) -> s
 
     # Replace external component path placeholder if present
     if "EXTERNAL_COMPONENT_PATH" in content:
-        external_components_path = str(
-            Path(__file__).parent / "fixtures" / "external_components"
-        )
+        external_components_path = str(FIXTURES_DIR / "external_components")
         content = content.replace("EXTERNAL_COMPONENT_PATH", external_components_path)
 
+    if shared_name is not None:
+        # _compile verifies the marked test compiles this content unmodified
+        request.node._shared_yaml_content = content
+
     return content
 
 
@@ -240,24 +270,218 @@ async def write_yaml_config(
 ) -> AsyncGenerator[ConfigWriter]:
     """Write YAML configuration to a file."""
     # Get the test name for default filename
-    test_name = request.node.name
-    base_name = test_name.replace("test_", "").split("[")[0]
+    base_name = request.node.name.replace("test_", "").partition("[")[0]
 
     async def _write_config(content: str, filename: str | None = None) -> Path:
         if filename is None:
             filename = f"{base_name}.yaml"
         config_path = integration_test_dir / filename
         loop = asyncio.get_running_loop()
-        await loop.run_in_executor(None, config_path.write_text, content)
+        await loop.run_in_executor(None, write_file, config_path, content)
         return config_path
 
     yield _write_config
 
 
+# Deliberately not CI-cached (ci.yml caches only platformio/ subpaths); stale
+# dirs for a fixture are pruned when its content hash changes.
+SHARED_BUILDS_ROOT = INTEGRATION_TESTS_ROOT / "builds"
+
+# In the dir name (not just the hash) so pruning stays inside this checkout
+_REPO_KEY = hashlib.sha256(str(REPO_ROOT).encode()).hexdigest()[:8]
+
+# Give a contended shared build lock time for a full cold compile ahead of us
+_SHARED_LOCK_TIMEOUT_S = 900
+_SHARED_LOCK_POLL_S = 0.1
+_SHARED_LOCK_REPORT_S = 30
+
+# Reclaims dirs orphaned by fixture renames or deleted checkouts
+_STALE_BUILD_MAX_AGE_S = 30 * 24 * 3600
+
+# ELF path per shared build dir; constant once compiled, so resolve it only once
+_shared_elf_paths: dict[Path, Path] = {}
+
+# Dirs this process already swept; pruning is session-scoped work
+_pruned_dirs: set[Path] = set()
+
+
+def _shared_yaml_name(request: pytest.FixtureRequest) -> str | None:
+    """Name passed to the shared_yaml marker, or None when unmarked."""
+    marker = request.node.get_closest_marker("shared_yaml")
+    if marker is None:
+        return None
+    # Exactly one \w+ positional arg: the name doubles as a build dir
+    # component, and CI test selection (script/helpers.py) parses the same shape
+    if (
+        len(marker.args) != 1
+        or marker.kwargs
+        or not re.fullmatch(r"\w+", str(marker.args[0]))
+    ):
+        raise ValueError(
+            "shared_yaml marker requires exactly one \\w+ fixture name literal"
+        )
+    return marker.args[0]
+
+
+def _shared_build_prefix(name: str) -> str:
+    return f"{name}-{_REPO_KEY}-"
+
+
+@cache
+def _shared_build_dir(name: str) -> Path:
+    """Dir keyed by checkout and fixture source, before per-test injections."""
+    key = hashlib.sha256((FIXTURES_DIR / f"{name}.yaml").read_bytes()).hexdigest()[:16]
+    return SHARED_BUILDS_ROOT / (_shared_build_prefix(name) + key)
+
+
+def _read_stamp(stamp: Path, shared_dir: Path) -> Path | None:
+    """ELF path recorded by the last completed compile, or None."""
+    try:
+        text = stamp.read_text(encoding="utf-8").strip()
+    except FileNotFoundError:
+        return None
+    except OSError as err:
+        print(f"Cannot read {stamp}: {err}")
+        return None
+    if not text:
+        print(f"Ignoring empty stamp {stamp}")
+        return None
+    built = Path(text)
+    # Never trust a stamp pointing outside its own build dir as an unlink target
+    if shared_dir.resolve() in built.resolve().parents:
+        return built
+    print(f"Ignoring stamp {stamp} pointing outside {shared_dir}")
+    return None
+
+
+def _unused_since(stale: Path, cutoff: float) -> bool:
+    """Whether a build dir looks untouched since cutoff; unknown counts as used."""
+    # Newest of the .built stamp (rewritten by every completed compile) and the
+    # dir itself (freshened by a worker claiming the dir before locking)
+    newest: float | None = None
+    for probe in (stale / ".built", stale):
+        try:
+            mtime = probe.stat().st_mtime
+        except FileNotFoundError:
+            continue
+        except NotADirectoryError:
+            return True  # a stray file where a dir should be; reclaimable
+        except OSError as err:
+            print(f"Cannot age-probe {stale}: {err}")
+            return False  # unknown never authorizes deletion
+        newest = mtime if newest is None else max(newest, mtime)
+    return newest is not None and newest < cutoff
+
+
+def _prune_stale_builds(name: str, keep: Path) -> None:
+    """Remove outdated build dirs (blocking, run in executor): this checkout's
+    other dirs for the fixture, plus anything untouched for 30 days. Tolerates
+    other workers pruning the same dirs concurrently."""
+    cutoff = time.time() - _STALE_BUILD_MAX_AGE_S
+    prefix = _shared_build_prefix(name)
+    for stale in SHARED_BUILDS_ROOT.iterdir():
+        if stale == keep:
+            continue
+        same_fixture = stale.name.startswith(prefix)
+        if not same_fixture and not _unused_since(stale, cutoff):
+            continue
+        # Creating .lock bumps the dir mtime, so remember whether the re-probe
+        # under the lock can trust it
+        lock_preexisting = (stale / ".lock").exists()
+        try:
+            lock_file = (stale / ".lock").open("w")
+        except FileNotFoundError:
+            continue  # pruned by another worker meanwhile
+        except NotADirectoryError:
+            print(f"Removing stray file {stale}")
+            stale.unlink(missing_ok=True)
+            continue
+        except OSError as err:
+            print(f"Cannot prune {stale}: {err}")
+            continue
+        with lock_file:
+            try:
+                fcntl.flock(lock_file.fileno(), fcntl.LOCK_EX | fcntl.LOCK_NB)
+            except BlockingIOError:
+                continue  # still in use by another run
+            # Re-probe under the lock: a worker freshens its dir before
+            # locking, so a just-claimed dir no longer looks unused. A dir
+            # whose .lock we just created cannot be held by anyone, and our
+            # own open bumped its mtime, so its pre-open probe stands
+            if (
+                lock_preexisting
+                and not same_fixture
+                and not _unused_since(stale, cutoff)
+            ):
+                continue
+            # rmtree tolerates races; a leftover partial tree only costs a
+            # rebuild, since the ELF is deleted before every compile
+            try:
+                rmtree(stale)
+            except OSError as err:
+                print(f"Failed to prune {stale}: {err}")
+
+
+async def _run_esphome_compile(
+    config_path: Path, cwd: Path, env: dict[str, str]
+) -> None:
+    """Run `esphome compile`, retrying up to 3 times on a segfault."""
+    max_retries = 3
+    for attempt in range(max_retries):
+        # Compile using subprocess, inheriting stdout/stderr to show progress
+        proc = await asyncio.create_subprocess_exec(
+            sys.executable,
+            "-m",
+            "esphome",
+            "compile",
+            str(config_path),
+            cwd=cwd,
+            stdout=None,  # Inherit stdout
+            stderr=None,  # Inherit stderr
+            stdin=asyncio.subprocess.DEVNULL,
+            # Start in a new process group to isolate signal handling
+            start_new_session=True,
+            env=env,
+            close_fds=False,
+        )
+        await proc.wait()
+
+        if proc.returncode == 0:
+            break
+        if proc.returncode == -11 and attempt < max_retries - 1:
+            # Segfault (-11 = SIGSEGV), retry
+            print(
+                f"Compilation segfaulted (attempt {attempt + 1}/{max_retries}), retrying..."
+            )
+            await asyncio.sleep(1)  # Brief pause before retry
+            continue
+        raise RuntimeError(
+            f"Failed to compile {config_path}, return code: {proc.returncode}. "
+            f"Run with 'pytest -s' to see compilation output."
+        )
+
+
+def _resolve_compiled_binary(config_path: Path) -> Path:
+    """Load the config to learn the compiled ELF path (blocking, run in executor)."""
+    CORE.reset()  # Reset CORE state between test runs
+    CORE.config_path = config_path
+    config = esphome.config.read_config(
+        {"command": "compile", "config": str(config_path)}
+    )
+    if config is None:
+        raise RuntimeError(f"Failed to read config from {config_path}")
+    idedata = get_idedata(config)
+    binary_path = Path(idedata.firmware_elf_path)
+    if not binary_path.exists():
+        raise RuntimeError(f"Compiled binary not found at {binary_path}")
+    return binary_path
+
+
 @pytest_asyncio.fixture
 async def compile_esphome(
     integration_test_dir: Path,
     shared_platformio_cache: Path,
+    request: pytest.FixtureRequest,
 ) -> AsyncGenerator[CompileFunction]:
     """Compile an ESPHome configuration and return the binary path."""
 
@@ -265,66 +489,96 @@ async def compile_esphome(
         # Use the shared PlatformIO cache for faster compilation
         # This avoids re-downloading dependencies for each test
         env = _get_platformio_env(shared_platformio_cache)
-
-        # Retry compilation up to 3 times if we get a segfault
-        max_retries = 3
-        for attempt in range(max_retries):
-            # Compile using subprocess, inheriting stdout/stderr to show progress
-            proc = await asyncio.create_subprocess_exec(
-                sys.executable,
-                "-m",
-                "esphome",
-                "compile",
-                str(config_path),
-                cwd=integration_test_dir,
-                stdout=None,  # Inherit stdout
-                stderr=None,  # Inherit stderr
-                stdin=asyncio.subprocess.DEVNULL,
-                # Start in a new process group to isolate signal handling
-                start_new_session=True,
-                env=env,
-                close_fds=False,
-            )
-            await proc.wait()
-
-            if proc.returncode == 0:
-                # Success!
-                break
-            if proc.returncode == -11 and attempt < max_retries - 1:
-                # Segfault (-11 = SIGSEGV), retry
-                print(
-                    f"Compilation segfaulted (attempt {attempt + 1}/{max_retries}), retrying..."
-                )
-                await asyncio.sleep(1)  # Brief pause before retry
-                continue
-            # Other error or final retry
-            raise RuntimeError(
-                f"Failed to compile {config_path}, return code: {proc.returncode}. "
-                f"Run with 'pytest -s' to see compilation output."
-            )
-
-        # Load the config to get idedata (blocking call, must use executor)
         loop = asyncio.get_running_loop()
 
-        def _read_config_and_get_binary():
-            CORE.reset()  # Reset CORE state between test runs
-            CORE.config_path = config_path
-            config = esphome.config.read_config(
-                {"command": "compile", "config": str(config_path)}
+        name = _shared_yaml_name(request)
+        if name is None:
+            await _run_esphome_compile(config_path, integration_test_dir, env)
+            return await loop.run_in_executor(
+                None, _resolve_compiled_binary, config_path
             )
-            if config is None:
-                raise RuntimeError(f"Failed to read config from {config_path}")
 
-            # Get the compiled binary path
-            idedata = get_idedata(config)
-            return Path(idedata.firmware_elf_path)
-
-        binary_path = await loop.run_in_executor(None, _read_config_and_get_binary)
-
-        if not binary_path.exists():
-            raise RuntimeError(f"Compiled binary not found at {binary_path}")
-
-        return binary_path
+        # Shared fixture: build in a hash-keyed dir so tests sharing a config
+        # pay one full compile and later only a main.cpp (port) rebuild + relink
+        shared_dir = _shared_build_dir(name)
+        shared_dir.mkdir(parents=True, exist_ok=True)
+        # Freshen the dir before locking so a concurrent age sweep, which
+        # re-probes under the lock, never reaps a dir a worker just claimed;
+        # if a peer reaped it already, the guarded lock open recreates it
+        with suppress(FileNotFoundError):
+            os.utime(shared_dir)
+        if shared_dir not in _pruned_dirs:
+            _pruned_dirs.add(shared_dir)
+            await loop.run_in_executor(None, _prune_stale_builds, name, shared_dir)
+        shared_config = shared_dir / f"{name}.yaml"
+        private_binary = integration_test_dir / f"{name}.elf"
+        content = await loop.run_in_executor(None, read_file, config_path)
+        if content != getattr(request.node, "_shared_yaml_content", None):
+            # The dir is keyed by the fixture source; a mutated config would be
+            # cached under a hash that does not describe it
+            raise RuntimeError(
+                "shared_yaml tests must compile the yaml_config content unmodified"
+            )
+        # flock serializes concurrent xdist workers; closing the fd releases it.
+        # Hand-rolled rather than filelock.FileLock: non-blocking retries keep
+        # the wait cancellable, while a blocking acquire in an executor thread
+        # would survive test cancellation holding the fd
+        try:
+            lock_file = (shared_dir / ".lock").open("w")
+        except FileNotFoundError:
+            # A peer run pruning divergent hashes reaped the dir between our
+            # mkdir and this open; recreate it and pay a full rebuild
+            shared_dir.mkdir(parents=True, exist_ok=True)
+            lock_file = (shared_dir / ".lock").open("w")
+        with lock_file:
+            start = time.monotonic()
+            last_report = start
+            while True:
+                try:
+                    fcntl.flock(lock_file.fileno(), fcntl.LOCK_EX | fcntl.LOCK_NB)
+                    break
+                except BlockingIOError:
+                    now = time.monotonic()
+                    if now - start > _SHARED_LOCK_TIMEOUT_S:
+                        raise RuntimeError(
+                            f"Timed out waiting for the {shared_dir} lock"
+                        ) from None
+                    if now - last_report >= _SHARED_LOCK_REPORT_S:
+                        last_report = now
+                        print(
+                            f"Waited {now - start:.0f}s for another worker's "
+                            f"build of {shared_dir.name}"
+                        )
+                    await asyncio.sleep(_SHARED_LOCK_POLL_S)
+            # .built carries the ELF path of the last completed compile, so
+            # later workers skip the config re-read in _resolve_compiled_binary
+            stamp = shared_dir / ".built"
+            if (built := _shared_elf_paths.get(shared_dir)) is None:
+                built = await loop.run_in_executor(None, _read_stamp, stamp, shared_dir)
+            # Delete the ELF before compiling: whatever exists afterwards is
+            # this compile's output, so no staleness check is ever needed.
+            # With no usable stamp, sweep any leftover at the known layout
+            if built is not None:
+                built.unlink(missing_ok=True)
+            else:
+                # Layout-agnostic: ESPHOME_BUILD_PATH can move the build tree
+                for leftover in shared_dir.rglob("program"):
+                    if leftover.is_file():
+                        leftover.unlink()
+            await loop.run_in_executor(
+                None, write_file_if_changed, shared_config, content
+            )
+            await _run_esphome_compile(shared_config, shared_dir, env)
+            if built is None or not built.exists():
+                built = await loop.run_in_executor(
+                    None, _resolve_compiled_binary, shared_config
+                )
+            _shared_elf_paths[shared_dir] = built
+            await loop.run_in_executor(None, write_file, stamp, str(built))
+            # Copy out before unlocking: another worker may relink firmware.elf
+            # while this test is still running its private copy
+            await loop.run_in_executor(None, shutil.copy2, built, private_binary)
+        return private_binary
 
     yield _compile
 

tests/integration/fixtures/api_decode_wire_types.yaml

@@ -0,0 +1,43 @@
+esphome:
+  name: api-decode-wire-types-test
+host:
+api:
+logger:
+  level: DEBUG
+
+switch:
+  - platform: template
+    name: "Wire Switch"
+    optimistic: true
+
+output:
+  - platform: template
+    id: wire_dim
+    type: float
+    write_action:
+      - lambda: ""
+
+light:
+  - platform: monochromatic
+    name: "Wire Light"
+    output: wire_dim
+    default_transition_length: 0s
+    effects:
+      - pulse:
+          name: Pulse
+
+text:
+  - platform: template
+    name: "Wire Text"
+    optimistic: true
+    mode: text
+    min_length: 0
+    max_length: 255
+
+number:
+  - platform: template
+    name: "Wire Number"
+    optimistic: true
+    min_value: -1000
+    max_value: 1000
+    step: 0.5

tests/integration/fixtures/api_empty_message_roundtrip.yaml

@@ -0,0 +1,11 @@
+esphome:
+  name: api-empty-message-test
+host:
+api:
+logger:
+  level: DEBUG
+
+switch:
+  - platform: template
+    name: "Empty Message Switch"
+    optimistic: true

tests/integration/fixtures/api_encode_boundaries.yaml

@@ -0,0 +1,58 @@
+esphome:
+  name: api-encode-boundaries-test
+  # Top-level area fills DeviceInfoResponse.suggested_area (field 16, a two-byte tag)
+  area:
+    id: kitchen_area
+    name: Kitchen
+  on_boot:
+    - sensor.template.publish:
+        id: zero_then_value
+        state: 0.0
+
+host:
+api:
+logger:
+  level: DEBUG
+
+sensor:
+  - platform: template
+    name: "Zero Then Value"
+    id: zero_then_value
+    # Negative int32 takes the ten byte varint path
+    accuracy_decimals: -2
+    update_interval: never
+
+text_sensor:
+  - platform: template
+    name: "Long Text"
+    id: long_text
+    update_interval: never
+
+number:
+  - platform: template
+    name: "Negative Number"
+    optimistic: true
+    min_value: -1000
+    max_value: 1000
+    step: 0.5
+    initial_value: -123.5
+
+select:
+  - platform: template
+    name: "Long Option Select"
+    optimistic: true
+    options:
+      - short
+      - "option-with-a-name-long-enough-that-its-length-prefix-needs-two-varint-bytes-when-the-list-entities-response-is-encoded-xxxxxxxxxx"
+    initial_option: short
+
+button:
+  - platform: template
+    name: "Publish Values"
+    on_press:
+      - sensor.template.publish:
+          id: zero_then_value
+          state: 12.5
+      - text_sensor.template.publish:
+          id: long_text
+          state: !lambda return std::string(200, 'y');

tests/integration/fixtures/sensor_filters_batch_window.yaml

@@ -1,58 +0,0 @@
-esphome:
-  name: test-batch-window-filters
-
-host:
-api:
-  batch_delay: 0ms  # Disable batching to receive all state updates
-logger:
-  level: DEBUG
-
-# Template sensor that we'll use to publish values
-sensor:
-  - platform: template
-    name: "Source Sensor"
-    id: source_sensor
-    accuracy_decimals: 2
-
-  # Batch window filters (window_size == send_every) - use streaming filters
-  - platform: copy
-    source_id: source_sensor
-    name: "Min Sensor"
-    id: min_sensor
-    filters:
-      - min:
-          window_size: 5
-          send_every: 5
-          send_first_at: 1
-
-  - platform: copy
-    source_id: source_sensor
-    name: "Max Sensor"
-    id: max_sensor
-    filters:
-      - max:
-          window_size: 5
-          send_every: 5
-          send_first_at: 1
-
-  - platform: copy
-    source_id: source_sensor
-    name: "Moving Avg Sensor"
-    id: moving_avg_sensor
-    filters:
-      - sliding_window_moving_average:
-          window_size: 5
-          send_every: 5
-          send_first_at: 1
-
-# Button to trigger publishing test values
-button:
-  - platform: template
-    name: "Publish Values Button"
-    id: publish_button
-    on_press:
-      - lambda: |-
-          // Publish 10 values: 1.0, 2.0, ..., 10.0
-          for (int i = 1; i <= 10; i++) {
-            id(source_sensor).publish_state(float(i));
-          }

tests/integration/fixtures/uart_mock_modbus_client_read_write.yaml

@@ -1,111 +0,0 @@
-esphome:
-  name: uart-mock-modbus-cli-rw
-
-host:
-api:
-logger:
-  level: VERBOSE
-
-external_components:
-  - source:
-      type: local
-      path: EXTERNAL_COMPONENT_PATH
-
-# Dummy uart entry to satisfy modbus's DEPENDENCIES = ["uart"]
-# The actual UART bus used is the uart_mock component below
-uart:
-  baud_rate: 115200
-  port: /dev/null
-
-# Two virtual buses looped back to each other: the client's transmissions reach the server and the
-# server's replies reach the client. auto_start so forwarding is active before the button fires.
-uart_mock:
-  - id: virtual_uart_server
-    baud_rate: 9600
-    auto_start: true
-    debug:
-    on_tx:
-      - then:
-          - uart_mock.inject_rx:
-              id: virtual_uart_client
-              data: !lambda return data;
-  - id: virtual_uart_client
-    baud_rate: 9600
-    auto_start: true
-    debug:
-    on_tx:
-      - then:
-          - uart_mock.inject_rx:
-              id: virtual_uart_server
-              data: !lambda return data;
-
-globals:
-  - id: stored_1
-    type: uint16_t
-    initial_value: "0"
-
-modbus:
-  - uart_id: virtual_uart_server
-    id: virtual_modbus_server
-    role: server
-  - uart_id: virtual_uart_client
-    id: virtual_modbus_client
-    role: client
-    turnaround_time: 10ms
-
-modbus_server:
-  - address: 1
-    modbus_id: virtual_modbus_server
-    registers:
-      # Writable + readable register: the read publishes what it returns, so the test can confirm the
-      # write half of the 0x17 ran before the read half (Modbus 6.17).
-      - address: 0x01
-        value_type: U_WORD
-        read_lambda: |-
-          id(srv_read_1).publish_state(id(stored_1));
-          return id(stored_1);
-        write_lambda: |-
-          id(stored_1) = x;
-          id(srv_write_1).publish_state(x);
-          return true;
-      # Read-only register, returned together with 0x01 by the 2-register read half.
-      - address: 0x02
-        value_type: U_WORD
-        read_lambda: return 0x00AA;
-
-sensor:
-  # Server-side observations.
-  - platform: template
-    name: "srv_write_1"
-    id: srv_write_1
-  - platform: template
-    name: "srv_read_1"
-    id: srv_read_1
-  # Client-side read-back: the values the client's on_response received.
-  - platform: template
-    name: "client_read_0"
-    id: client_read_0
-  - platform: template
-    name: "client_read_1"
-    id: client_read_1
-
-button:
-  - platform: template
-    name: "Start Scenario"
-    id: start_scenario_btn
-    on_press:
-      # FC 0x17: write reg 0x0001 = 0x1234, then read regs 0x0001..0x0002 back in the same transaction.
-      - modbus_client.read_write_multiple_registers:
-          address: 0x01
-          read_address: 0x0001
-          read_count: 2
-          write_address: 0x0001
-          values: [0x1234]
-          on_response:
-            then:
-              - lambda: |-
-                  // values is the read-back block: reg 0x0001 (must be the just-written 0x1234) and reg 0x0002.
-                  if (values.size() >= 2) {
-                    id(client_read_0).publish_state(values[0]);
-                    id(client_read_1).publish_state(values[1]);
-                  }

tests/integration/fixtures/uart_mock_modbus_custom_pdu.yaml

@@ -1,88 +0,0 @@
-esphome:
-  name: uart-mock-modbus-custom-pdu
-
-host:
-api:
-logger:
-  level: VERBOSE
-
-external_components:
-  - source:
-      type: local
-      path: EXTERNAL_COMPONENT_PATH
-
-# Dummy uart entry to satisfy modbus's DEPENDENCIES = ["uart"]
-# The actual UART bus used is the uart_mock component below
-uart:
-  baud_rate: 115200
-  port: /dev/null
-
-uart_mock:
-  - id: virtual_uart_server
-    baud_rate: 9600
-    auto_start: true
-    debug:
-    on_tx:
-      - then:
-          - uart_mock.inject_rx:
-              id: virtual_uart_controller
-              data: !lambda return data;
-  - id: virtual_uart_controller
-    baud_rate: 9600
-    auto_start: true
-    debug:
-    on_tx:
-      - then:
-          - uart_mock.inject_rx:
-              id: virtual_uart_server
-              data: !lambda return data;
-
-modbus:
-  - uart_id: virtual_uart_server
-    id: virtual_modbus_server
-    role: server
-  - uart_id: virtual_uart_controller
-    id: virtual_modbus_controller
-    role: client
-    turnaround_time: 10ms
-
-modbus_controller:
-  - address: 1
-    modbus_id: virtual_modbus_controller
-    id: modbus_controller_1
-    update_interval: 1s
-
-modbus_server:
-  - address: 1
-    modbus_id: virtual_modbus_server
-    id: modbus_server_1
-    registers:
-      - address: 0x01
-        value_type: U_WORD
-        read_lambda: return 259;
-
-sensor:
-  # Plain read to confirm the controller <-> server link is up.
-  - platform: modbus_controller
-    modbus_controller_id: modbus_controller_1
-    name: "plain_read"
-    address: 0x01
-    register_type: holding
-    value_type: U_WORD
-  # Custom PDU: read holding register 0x0001, count 1. The PDU is
-  # {function code, address hi, address lo, count hi, count lo}; the device
-  # address and CRC are added by the hub. The lambda parses the response payload
-  # (the register value, big-endian).
-  - platform: modbus_controller
-    modbus_controller_id: modbus_controller_1
-    name: "custom_read"
-    custom_pdu: [0x03, 0x00, 0x01, 0x00, 0x01]
-    lambda: |-
-      if (data.size() < 2) return {};
-      return (float) ((data[0] << 8) | data[1]);
-
-button:
-  - platform: template
-    name: "Start Scenario"
-    id: start_scenario_btn
-    # This test does not have anything to start (mock is autostart)

tests/integration/fixtures/uart_mock_modbus_deprecated_write_buffer.yaml

@@ -1,106 +0,0 @@
-esphome:
-  name: uart-mock-modbus-dep-buffer
-
-host:
-api:
-logger:
-  level: VERBOSE
-
-external_components:
-  - source:
-      type: local
-      path: EXTERNAL_COMPONENT_PATH
-
-# Dummy uart entry to satisfy modbus's DEPENDENCIES = ["uart"]
-# The actual UART bus used is the uart_mock component below
-uart:
-  baud_rate: 115200
-  port: /dev/null
-
-uart_mock:
-  - id: virtual_uart_server
-    baud_rate: 9600
-    auto_start: true
-    debug:
-    on_tx:
-      - then:
-          - uart_mock.inject_rx:
-              id: virtual_uart_controller
-              data: !lambda return data;
-  - id: virtual_uart_controller
-    baud_rate: 9600
-    auto_start: true
-    debug:
-    on_tx:
-      - then:
-          - uart_mock.inject_rx:
-              id: virtual_uart_server
-              data: !lambda return data;
-
-globals:
-  - id: reg10
-    type: uint16_t
-    initial_value: "0"
-
-modbus:
-  - uart_id: virtual_uart_server
-    id: virtual_modbus_server
-    role: server
-  - uart_id: virtual_uart_controller
-    id: virtual_modbus_controller
-    role: client
-    turnaround_time: 10ms
-
-modbus_controller:
-  - address: 1
-    modbus_id: virtual_modbus_controller
-    id: modbus_controller_1
-    update_interval: 1s
-
-modbus_server:
-  - address: 1
-    modbus_id: virtual_modbus_server
-    id: modbus_server_1
-    registers:
-      - address: 0x10
-        value_type: U_WORD
-        read_lambda: return id(reg10);
-        write_lambda: |-
-          id(reg10) = x;
-          return true;
-
-# A number whose write_lambda uses the DEPRECATED buffer parameter (fills `payload` with a legacy raw
-# frame as words: device address + function code + data) instead of the new item->write_* API. The write
-# must still land with its legacy semantics, and the one-time deprecation warning must fire only once per
-# entity no matter how many writes happen.
-number:
-  - platform: modbus_controller
-    modbus_controller_id: modbus_controller_1
-    name: "buf_number"
-    id: buf_number
-    address: 0x10
-    register_type: holding
-    value_type: U_WORD
-    min_value: 0
-    max_value: 1000
-    step: 1
-    write_lambda: |-
-      // Legacy raw frame as words: [addr 0x01 | fc 0x06], register 0x0010, value.
-      payload.push_back(0x0106);
-      payload.push_back(0x0010);
-      payload.push_back((uint16_t) x);
-      return {};
-
-# Reports the server-side register so the test can observe that the deprecated buffer write landed.
-sensor:
-  - platform: template
-    name: "written_value"
-    id: written_value
-    update_interval: 0.5s
-    lambda: "return id(reg10);"
-
-button:
-  - platform: template
-    name: "Start Scenario"
-    id: start_scenario_btn
-    # The test drives the writes via number_command; the mock is autostart.

tests/integration/fixtures/uart_mock_modbus_lambda_invert.yaml

@@ -1,95 +0,0 @@
-esphome:
-  name: uart-mock-modbus-lambda-invert
-
-host:
-api:
-logger:
-  level: VERBOSE
-
-external_components:
-  - source:
-      type: local
-      path: EXTERNAL_COMPONENT_PATH
-
-# Dummy uart entry to satisfy modbus's DEPENDENCIES = ["uart"]
-# The actual UART bus used is the uart_mock component below
-uart:
-  baud_rate: 115200
-  port: /dev/null
-
-uart_mock:
-  - id: virtual_uart_server
-    baud_rate: 9600
-    auto_start: true
-    debug:
-    on_tx:
-      - then:
-          - uart_mock.inject_rx:
-              id: virtual_uart_controller
-              data: !lambda return data;
-  - id: virtual_uart_controller
-    baud_rate: 9600
-    auto_start: true
-    debug:
-    on_tx:
-      - then:
-          - uart_mock.inject_rx:
-              id: virtual_uart_server
-              data: !lambda return data;
-
-globals:
-  - id: reg40
-    type: uint16_t
-    initial_value: "5"
-
-modbus:
-  - uart_id: virtual_uart_server
-    id: virtual_modbus_server
-    role: server
-  - uart_id: virtual_uart_controller
-    id: virtual_modbus_controller
-    role: client
-    turnaround_time: 10ms
-
-modbus_controller:
-  - address: 1
-    modbus_id: virtual_modbus_controller
-    id: modbus_controller_1
-    update_interval: 1s
-
-modbus_server:
-  - address: 1
-    modbus_id: virtual_modbus_server
-    id: modbus_server_1
-    registers:
-      - address: 0x40
-        value_type: U_WORD
-        read_lambda: return id(reg40);
-        write_lambda: id(reg40) = x; return true;
-
-# An active-low holding switch: the write_lambda inverts the wire value, but the entity must still
-# report the REQUESTED state. assumed_state keeps the register unpolled, so the published state comes
-# only from write_state() - turning ON writes 0x0000 yet the switch shows ON.
-switch:
-  - platform: modbus_controller
-    modbus_controller_id: modbus_controller_1
-    name: "invert_switch"
-    register_type: holding
-    address: 0x40
-    assumed_state: true
-    write_lambda: |-
-      return !x;
-
-sensor:
-  - platform: modbus_controller
-    modbus_controller_id: modbus_controller_1
-    name: "reg_40"
-    address: 0x40
-    register_type: holding
-    value_type: U_WORD
-
-button:
-  - platform: template
-    name: "Start Scenario"
-    id: start_scenario_btn
-    # This test does not have anything to start (mock is autostart)

tests/integration/fixtures/uart_mock_modbus_lambda_write.yaml

@@ -1,97 +0,0 @@
-esphome:
-  name: uart-mock-modbus-lambda-write
-
-host:
-api:
-logger:
-  level: VERBOSE
-
-external_components:
-  - source:
-      type: local
-      path: EXTERNAL_COMPONENT_PATH
-
-# Dummy uart entry to satisfy modbus's DEPENDENCIES = ["uart"]
-# The actual UART bus used is the uart_mock component below
-uart:
-  baud_rate: 115200
-  port: /dev/null
-
-uart_mock:
-  - id: virtual_uart_server
-    baud_rate: 9600
-    auto_start: true
-    debug:
-    on_tx:
-      - then:
-          - uart_mock.inject_rx:
-              id: virtual_uart_controller
-              data: !lambda return data;
-  - id: virtual_uart_controller
-    baud_rate: 9600
-    auto_start: true
-    debug:
-    on_tx:
-      - then:
-          - uart_mock.inject_rx:
-              id: virtual_uart_server
-              data: !lambda return data;
-
-globals:
-  - id: reg30
-    type: uint16_t
-    initial_value: "0"
-
-modbus:
-  - uart_id: virtual_uart_server
-    id: virtual_modbus_server
-    role: server
-  - uart_id: virtual_uart_controller
-    id: virtual_modbus_controller
-    role: client
-    turnaround_time: 10ms
-
-modbus_controller:
-  - address: 1
-    modbus_id: virtual_modbus_controller
-    id: modbus_controller_1
-    update_interval: 1s
-
-modbus_server:
-  - address: 1
-    modbus_id: virtual_modbus_server
-    id: modbus_server_1
-    registers:
-      - address: 0x30
-        value_type: U_WORD
-        read_lambda: return id(reg30);
-        write_lambda: id(reg30) = x; return true;
-
-# A COIL-type switch (assumed_state, write-only) whose write_lambda ignores its own coil type and instead
-# drives a HOLDING-REGISTER write on the mock server through the entity itself: `item` IS the command, so
-# item->write_single_register() sends a register write from a coil entity (cross-type). Returning nothing
-# (an empty optional) tells the write path the lambda already dispatched the frame - no default coil write.
-switch:
-  - platform: modbus_controller
-    modbus_controller_id: modbus_controller_1
-    name: "cross_switch"
-    register_type: coil
-    address: 0x00
-    assumed_state: true
-    write_lambda: |-
-      item->write_single_register(0x30, x ? 1234 : 0);
-      return {};
-
-sensor:
-  - platform: modbus_controller
-    modbus_controller_id: modbus_controller_1
-    name: "reg_30"
-    address: 0x30
-    register_type: holding
-    value_type: U_WORD
-
-button:
-  - platform: template
-    name: "Start Scenario"
-    id: start_scenario_btn
-    # This test does not have anything to start (mock is autostart)

tests/integration/fixtures/uart_mock_modbus_loopback.yaml

@@ -0,0 +1,233 @@
+esphome:
+  name: uart-mock-modbus-loopback
+
+host:
+api:
+logger:
+  level: VERBOSE
+
+external_components:
+  - source:
+      type: local
+      path: EXTERNAL_COMPONENT_PATH
+
+# Dummy uart entry to satisfy modbus's DEPENDENCIES = ["uart"]
+# The actual UART bus used is the uart_mock component below
+uart:
+  baud_rate: 115200
+  port: /dev/null
+
+# Shared loopback fixture (see the shared_yaml markers in the test file);
+# register spaces are disjoint so each test only observes its own entities.
+uart_mock:
+  - id: virtual_uart_server
+    baud_rate: 9600
+    auto_start: true
+    debug:
+    on_tx:
+      - then:
+          - uart_mock.inject_rx:
+              id: virtual_uart_controller
+              data: !lambda return data;
+  - id: virtual_uart_controller
+    baud_rate: 9600
+    auto_start: true
+    debug:
+    on_tx:
+      - then:
+          - uart_mock.inject_rx:
+              id: virtual_uart_server
+              data: !lambda return data;
+
+globals:
+  - id: reg10
+    type: uint16_t
+    initial_value: "100"
+  - id: reg11
+    type: uint16_t
+    initial_value: "200"
+  - id: reg12
+    type: uint16_t
+    initial_value: "300"
+  - id: reg13
+    type: uint16_t
+    initial_value: "0xABCD"
+  - id: reg30
+    type: uint16_t
+    initial_value: "0"
+  - id: reg40
+    type: uint16_t
+    initial_value: "5"
+  - id: reg50
+    type: uint16_t
+    initial_value: "0"
+
+modbus:
+  - uart_id: virtual_uart_server
+    id: virtual_modbus_server
+    role: server
+  - uart_id: virtual_uart_controller
+    id: virtual_modbus_controller
+    role: client
+    turnaround_time: 10ms
+
+modbus_controller:
+  - address: 1
+    modbus_id: virtual_modbus_controller
+    id: modbus_controller_1
+    update_interval: 1s
+
+modbus_server:
+  - address: 1
+    modbus_id: virtual_modbus_server
+    registers:
+      - address: 0x01
+        value_type: U_WORD
+        read_lambda: return 259;
+      - address: 0x10
+        value_type: U_WORD
+        read_lambda: return id(reg10);
+        write_lambda: id(reg10) = x; return true;
+      - address: 0x11
+        value_type: U_WORD
+        read_lambda: return id(reg11);
+        write_lambda: id(reg11) = x; return true;
+      - address: 0x12
+        value_type: U_WORD
+        read_lambda: return id(reg12);
+        write_lambda: id(reg12) = x; return true;
+      - address: 0x13
+        value_type: U_WORD
+        read_lambda: return id(reg13);
+      - address: 0x30
+        value_type: U_WORD
+        read_lambda: return id(reg30);
+        write_lambda: id(reg30) = x; return true;
+      - address: 0x40
+        value_type: U_WORD
+        read_lambda: return id(reg40);
+        write_lambda: id(reg40) = x; return true;
+      - address: 0x50
+        value_type: U_WORD
+        read_lambda: return id(reg50);
+        write_lambda: id(reg50) = x; return true;
+
+# Byte-based offset: 2 bytes -> register 0x11 (the old code folded it in as a
+# register count, hitting 0x12). assumed_state keeps the switch write-only.
+switch:
+  - platform: modbus_controller
+    modbus_controller_id: modbus_controller_1
+    name: "offset_switch"
+    register_type: holding
+    address: 0x10
+    offset: 2
+    assumed_state: true
+  # Reading switch, byte offset 6 -> register 0x13; the pre-fix resolution (0x16)
+  # would draw ILLEGAL_DATA_ADDRESS and never publish.
+  - platform: modbus_controller
+    modbus_controller_id: modbus_controller_1
+    name: "read_offset_switch"
+    register_type: holding
+    address: 0x10
+    offset: 6
+    bitmask: 0x1
+  # Coil switch whose write_lambda dispatches a holding-register write via `item`;
+  # returning an empty optional suppresses the default coil write.
+  - platform: modbus_controller
+    modbus_controller_id: modbus_controller_1
+    name: "cross_switch"
+    register_type: coil
+    address: 0x00
+    assumed_state: true
+    write_lambda: |-
+      item->write_single_register(0x30, x ? 1234 : 0);
+      return {};
+  # Active-low: the write_lambda inverts the wire value but the entity must still
+  # report the requested state (assumed_state keeps the register unpolled).
+  - platform: modbus_controller
+    modbus_controller_id: modbus_controller_1
+    name: "invert_switch"
+    register_type: holding
+    address: 0x40
+    assumed_state: true
+    write_lambda: |-
+      return !x;
+
+# Uses the deprecated buffer parameter (legacy raw frame as words); the write
+# must land and the deprecation warning must fire only once per entity.
+number:
+  - platform: modbus_controller
+    modbus_controller_id: modbus_controller_1
+    name: "buf_number"
+    id: buf_number
+    address: 0x50
+    register_type: holding
+    value_type: U_WORD
+    min_value: 0
+    max_value: 1000
+    step: 1
+    write_lambda: |-
+      // Legacy raw frame as words: [addr 0x01 | fc 0x06], register 0x0050, value.
+      payload.push_back(0x0106);
+      payload.push_back(0x0050);
+      payload.push_back((uint16_t) x);
+      return {};
+
+sensor:
+  - platform: modbus_controller
+    modbus_controller_id: modbus_controller_1
+    name: "plain_read"
+    address: 0x01
+    register_type: holding
+    value_type: U_WORD
+  # Custom PDU: read holding register 0x0001; device address and CRC are added
+  # by the hub. The lambda parses the big-endian register value.
+  - platform: modbus_controller
+    modbus_controller_id: modbus_controller_1
+    name: "custom_read"
+    custom_pdu: [0x03, 0x00, 0x01, 0x00, 0x01]
+    lambda: |-
+      if (data.size() < 2) return {};
+      return (float) ((data[0] << 8) | data[1]);
+  - platform: modbus_controller
+    modbus_controller_id: modbus_controller_1
+    name: "reg_10"
+    address: 0x10
+    register_type: holding
+    value_type: U_WORD
+  - platform: modbus_controller
+    modbus_controller_id: modbus_controller_1
+    name: "reg_11"
+    address: 0x11
+    register_type: holding
+    value_type: U_WORD
+  - platform: modbus_controller
+    modbus_controller_id: modbus_controller_1
+    name: "reg_12"
+    address: 0x12
+    register_type: holding
+    value_type: U_WORD
+  - platform: modbus_controller
+    modbus_controller_id: modbus_controller_1
+    name: "reg_30"
+    address: 0x30
+    register_type: holding
+    value_type: U_WORD
+  - platform: modbus_controller
+    modbus_controller_id: modbus_controller_1
+    name: "reg_40"
+    address: 0x40
+    register_type: holding
+    value_type: U_WORD
+  # Reports the server-side register so the test can observe that the deprecated buffer write landed.
+  - platform: template
+    name: "written_value"
+    id: written_value
+    update_interval: 0.5s
+    lambda: "return id(reg50);"
+
+button:
+  - platform: template
+    name: "Start Scenario"
+    id: start_scenario_btn
+    # Nothing to start (mock is autostart); tests drive entities directly

tests/integration/fixtures/uart_mock_modbus_mesh.yaml

@@ -1,5 +1,5 @@
 esphome:
-  name: uart-mock-modbus-server-contro
+  name: uart-mock-modbus-mesh
 
 host:
 api:
@@ -17,13 +17,14 @@ uart:
   baud_rate: 115200
   port: /dev/null
 
+# Shared 3-bus mesh (see the shared_yaml markers): addr 1 = typed read-only
+# registers, addr 5 = the read/write 0x17 target, addr 2/3 on the second
+# server hub. auto_start everywhere: the controller polls at boot, so the
+# forwarding must already be live or early requests generate warnings.
+# Every test presses Start Scenario, so all merged actions fire in every test.
 uart_mock:
   - id: virtual_uart_server
     baud_rate: 9600
-    # auto_start must be true for loopback fixtures: the modbus controller
-    # polls on its update_interval immediately at boot, so the uart_mock
-    # forwarding must already be active or early requests are lost and
-    # generate modbus warnings.
     auto_start: true
     debug:
     on_tx:
@@ -31,35 +32,68 @@ uart_mock:
           - uart_mock.inject_rx:
               id: virtual_uart_controller
               data: !lambda return data;
-  - id: virtual_uart_controller
+          - uart_mock.inject_rx:
+              id: virtual_uart_server_2
+              data: !lambda return data;
+  - id: virtual_uart_server_2
     baud_rate: 9600
-    auto_start: true # See comment on virtual_uart_server above
+    auto_start: true
     debug:
     on_tx:
       - then:
           - uart_mock.inject_rx:
               id: virtual_uart_server
               data: !lambda return data;
+          - uart_mock.inject_rx:
+              id: virtual_uart_controller
+              data: !lambda return data;
+  - id: virtual_uart_controller
+    baud_rate: 9600
+    auto_start: true
+    debug:
+    on_tx:
+      - then:
+          - uart_mock.inject_rx:
+              id: virtual_uart_server
+              data: !lambda return data;
+          - uart_mock.inject_rx:
+              id: virtual_uart_server_2
+              data: !lambda return data;
+
+globals:
+  - id: stored_1
+    type: uint16_t
+    initial_value: "0"
 
 modbus:
   - uart_id: virtual_uart_server
     id: virtual_modbus_server
     role: server
+  - uart_id: virtual_uart_server_2
+    id: virtual_modbus_server_2
+    role: server
   - uart_id: virtual_uart_controller
-    id: virtual_modbus_controller
+    id: virtual_modbus_client
     role: client
     turnaround_time: 10ms
 
 modbus_controller:
   - address: 1
-    modbus_id: virtual_modbus_controller
+    modbus_id: virtual_modbus_client
     id: modbus_controller_1
     update_interval: 1s
+  - address: 2
+    modbus_id: virtual_modbus_client
+    id: modbus_controller_2
+    update_interval: 1s
+  - address: 3
+    modbus_id: virtual_modbus_client
+    id: modbus_controller_3
+    update_interval: 1s
 
 modbus_server:
   - address: 1
     modbus_id: virtual_modbus_server
-    id: modbus_server_1
     registers:
       - address: 0x01
         value_type: U_WORD
@@ -103,6 +137,34 @@ modbus_server:
       - address: 0x28
         value_type: FP32_R
         read_lambda: return 3.14;
+  - address: 5
+    modbus_id: virtual_modbus_server
+    registers:
+      # Writable + readable register: srv_write_1 plus the client's read-back
+      # confirm the write half of the 0x17 ran before the read half (Modbus 6.17).
+      - address: 0x01
+        value_type: U_WORD
+        read_lambda: return id(stored_1);
+        write_lambda: |-
+          id(stored_1) = x;
+          id(srv_write_1).publish_state(x);
+          return true;
+      # Read-only register, returned together with 0x01 by the 2-register read half.
+      - address: 0x02
+        value_type: U_WORD
+        read_lambda: return 0x00AA;
+  - address: 2
+    modbus_id: virtual_modbus_server_2
+    registers:
+      - address: 0x01
+        value_type: U_WORD
+        read_lambda: return 919;
+  - address: 3
+    modbus_id: virtual_modbus_server_2
+    registers:
+      - address: 0x01
+        value_type: U_WORD
+        read_lambda: return 929;
 
 sensor:
   - platform: modbus_controller
@@ -195,9 +257,46 @@ sensor:
     address: 0x28
     register_type: holding
     value_type: FP32_R
+  - platform: modbus_controller
+    modbus_controller_id: modbus_controller_2
+    name: "multi_reg_a"
+    address: 0x01
+    register_type: holding
+    value_type: U_WORD
+  - platform: modbus_controller
+    modbus_controller_id: modbus_controller_3
+    name: "multi_reg_b"
+    address: 0x01
+    register_type: holding
+    value_type: U_WORD
+  # client_read_write observations, server- and client-side.
+  - platform: template
+    name: "srv_write_1"
+    id: srv_write_1
+  - platform: template
+    name: "client_read_0"
+    id: client_read_0
+  - platform: template
+    name: "client_read_1"
+    id: client_read_1
 
 button:
   - platform: template
     name: "Start Scenario"
     id: start_scenario_btn
-    # This test does not have anything to start (mock is autostart)
+    on_press:
+      # FC 0x17: write reg 0x0001 = 0x1234, then read regs 0x0001..0x0002 back in the same transaction.
+      - modbus_client.read_write_multiple_registers:
+          address: 5
+          read_address: 0x0001
+          read_count: 2
+          write_address: 0x0001
+          values: [0x1234]
+          on_response:
+            then:
+              - lambda: |-
+                  // values is the read-back block: reg 0x0001 (must be the just-written 0x1234) and reg 0x0002.
+                  if (values.size() >= 2) {
+                    id(client_read_0).publish_state(values[0]);
+                    id(client_read_1).publish_state(values[1]);
+                  }

tests/integration/fixtures/uart_mock_modbus_register_offset.yaml

@@ -1,138 +0,0 @@
-esphome:
-  name: uart-mock-modbus-reg-offset
-
-host:
-api:
-logger:
-  level: VERBOSE
-
-external_components:
-  - source:
-      type: local
-      path: EXTERNAL_COMPONENT_PATH
-
-# Dummy uart entry to satisfy modbus's DEPENDENCIES = ["uart"]
-# The actual UART bus used is the uart_mock component below
-uart:
-  baud_rate: 115200
-  port: /dev/null
-
-uart_mock:
-  - id: virtual_uart_server
-    baud_rate: 9600
-    auto_start: true
-    debug:
-    on_tx:
-      - then:
-          - uart_mock.inject_rx:
-              id: virtual_uart_controller
-              data: !lambda return data;
-  - id: virtual_uart_controller
-    baud_rate: 9600
-    auto_start: true
-    debug:
-    on_tx:
-      - then:
-          - uart_mock.inject_rx:
-              id: virtual_uart_server
-              data: !lambda return data;
-
-globals:
-  - id: reg10
-    type: uint16_t
-    initial_value: "100"
-  - id: reg11
-    type: uint16_t
-    initial_value: "200"
-  - id: reg12
-    type: uint16_t
-    initial_value: "300"
-  - id: reg13
-    type: uint16_t
-    initial_value: "0xABCD"
-
-modbus:
-  - uart_id: virtual_uart_server
-    id: virtual_modbus_server
-    role: server
-  - uart_id: virtual_uart_controller
-    id: virtual_modbus_controller
-    role: client
-    turnaround_time: 10ms
-
-modbus_controller:
-  - address: 1
-    modbus_id: virtual_modbus_controller
-    id: modbus_controller_1
-    update_interval: 1s
-
-modbus_server:
-  - address: 1
-    modbus_id: virtual_modbus_server
-    id: modbus_server_1
-    registers:
-      - address: 0x10
-        value_type: U_WORD
-        read_lambda: return id(reg10);
-        write_lambda: id(reg10) = x; return true;
-      - address: 0x11
-        value_type: U_WORD
-        read_lambda: return id(reg11);
-        write_lambda: id(reg11) = x; return true;
-      - address: 0x12
-        value_type: U_WORD
-        read_lambda: return id(reg12);
-        write_lambda: id(reg12) = x; return true;
-      - address: 0x13
-        value_type: U_WORD
-        read_lambda: return id(reg13);
-        write_lambda: id(reg13) = x; return true;
-
-# A holding-register switch at 0x10 with a 2-BYTE offset. offset is byte-based, so the write must target
-# register 0x10 + 2/2 = 0x11. The old (pre-fix) behavior folded offset into the address as a register
-# count, hitting 0x12 instead. assumed_state keeps the switch write-only so it does not read any register.
-switch:
-  - platform: modbus_controller
-    modbus_controller_id: modbus_controller_1
-    name: "offset_switch"
-    register_type: holding
-    address: 0x10
-    offset: 2
-    assumed_state: true
-  # A holding-register switch that READS its state. Byte offset 6 -> register 0x10 + 6/2 = 0x13. Post-fix
-  # the switch itself resolves to 0x13 (the even byte offset folds into the address as whole registers) and
-  # joins the 0x10..0x13 range, so no separate 0x13 sensor is needed. Pre-fix the whole byte offset folds
-  # into the address (0x16), where the server answers ILLEGAL_DATA_ADDRESS and the switch never publishes.
-  - platform: modbus_controller
-    modbus_controller_id: modbus_controller_1
-    name: "read_offset_switch"
-    register_type: holding
-    address: 0x10
-    offset: 6
-    bitmask: 0x1
-
-sensor:
-  - platform: modbus_controller
-    modbus_controller_id: modbus_controller_1
-    name: "reg_10"
-    address: 0x10
-    register_type: holding
-    value_type: U_WORD
-  - platform: modbus_controller
-    modbus_controller_id: modbus_controller_1
-    name: "reg_11"
-    address: 0x11
-    register_type: holding
-    value_type: U_WORD
-  - platform: modbus_controller
-    modbus_controller_id: modbus_controller_1
-    name: "reg_12"
-    address: 0x12
-    register_type: holding
-    value_type: U_WORD
-
-button:
-  - platform: template
-    name: "Start Scenario"
-    id: start_scenario_btn
-    # This test does not have anything to start (mock is autostart)

tests/integration/fixtures/uart_mock_modbus_server.yaml

@@ -1,124 +0,0 @@
-esphome:
-  name: uart-mock-modbus-server-test
-
-host:
-api:
-logger:
-  level: VERBOSE
-
-external_components:
-  - source:
-      type: local
-      path: EXTERNAL_COMPONENT_PATH
-
-# Dummy uart entry to satisfy modbus's DEPENDENCIES = ["uart"]
-# The actual UART bus used is the uart_mock component below
-uart:
-  baud_rate: 115200
-  port: /dev/null
-
-uart_mock:
-  - id: virtual_uart_dev
-    baud_rate: 9600
-    rx_full_threshold: 120
-    rx_timeout: 2
-    auto_start: false
-    debug:
-    injections:
-      - delay: 100ms
-        inject_rx: [0x01, 0x03, 0x00, 0x03, 0x00, 0x01, 0x74, 0x0A] #  Read holding register 3 on device 1 (basic_read)
-      - delay: 100ms
-        #  Read holding register 7 on device 2
-        #  Reply from device 2
-        #  Read holding register 5 on device 1 (read_after_peer_response)
-        inject_rx:
-          [
-            0x02,
-            0x03,
-            0x00,
-            0x07,
-            0x00,
-            0x01,
-            0x35,
-            0xF8,
-            0x02,
-            0x03,
-            0x02,
-            0x00,
-            0xF0,
-            0xFC,
-            0x00,
-            0x01,
-            0x03,
-            0x00,
-            0x05,
-            0x00,
-            0x01,
-            0x94,
-            0x0B,
-          ]
-      - delay: 100ms
-        inject_rx: [0x02, 0x03, 0x00, 0x07, 0x00, 0x01, 0x35, 0xF8] #  Read holding register 7 on device 2, with no response
-      - delay: 100ms
-        #  Read holding register 7 on device 2, with no response
-        #  Read holding register A on device 1 (read_after_peer_timeout)
-        inject_rx:
-          [
-            0x02,
-            0x03,
-            0x00,
-            0x07,
-            0x00,
-            0x01,
-            0x35,
-            0xF8,
-            0x01,
-            0x03,
-            0x00,
-            0x0A,
-            0x00,
-            0x01,
-            0xA4,
-            0x08,
-          ]
-
-modbus:
-  uart_id: virtual_uart_dev
-  role: server
-
-modbus_server:
-  - address: 1
-    registers:
-      - address: 0x03
-        value_type: U_WORD
-        read_lambda: |-
-          id(basic_read).publish_state(1);
-          return 1;
-      - address: 0x05
-        value_type: U_WORD
-        read_lambda: |-
-          id(read_after_peer_response).publish_state(1);
-          return 1;
-      - address: 0x0A
-        value_type: U_WORD
-        read_lambda: |-
-          id(read_after_peer_timeout).publish_state(1);
-          return 1;
-
-sensor:
-  - platform: template
-    name: "basic_read"
-    id: basic_read
-  - platform: template
-    name: "read_after_peer_response"
-    id: read_after_peer_response
-  - platform: template
-    name: "read_after_peer_timeout"
-    id: read_after_peer_timeout
-
-button:
-  - platform: template
-    name: "Start Scenario"
-    id: start_scenario_btn
-    on_press:
-      - lambda: "id(virtual_uart_dev).start_scenario();"

tests/integration/fixtures/uart_mock_modbus_server_controller_multiple.yaml

@@ -1,116 +0,0 @@
-esphome:
-  name: uart-mock-modbus-server-mult
-
-host:
-api:
-logger:
-  level: VERBOSE
-
-external_components:
-  - source:
-      type: local
-      path: EXTERNAL_COMPONENT_PATH
-
-# Dummy uart entry to satisfy modbus's DEPENDENCIES = ["uart"]
-# The actual UART bus used is the uart_mock component below
-uart:
-  baud_rate: 115200
-  port: /dev/null
-
-uart_mock:
-  - id: virtual_uart_server
-    baud_rate: 9600
-    # auto_start must be true for loopback fixtures: the modbus controller
-    # polls on its update_interval immediately at boot, so the uart_mock
-    # forwarding must already be active or early requests are lost and
-    # generate modbus warnings.
-    auto_start: true
-    debug:
-    on_tx:
-      - then:
-          - uart_mock.inject_rx:
-              id: virtual_uart_controller
-              data: !lambda return data;
-          - uart_mock.inject_rx:
-              id: virtual_uart_server_2
-              data: !lambda return data;
-  - id: virtual_uart_server_2
-    baud_rate: 9600
-    auto_start: true # See comment on virtual_uart_server above
-    debug:
-    on_tx:
-      - then:
-          - uart_mock.inject_rx:
-              id: virtual_uart_server
-              data: !lambda return data;
-          - uart_mock.inject_rx:
-              id: virtual_uart_controller
-              data: !lambda return data;
-  - id: virtual_uart_controller
-    baud_rate: 9600
-    auto_start: true # See comment on virtual_uart_server above
-    debug:
-    on_tx:
-      - then:
-          - uart_mock.inject_rx:
-              id: virtual_uart_server
-              data: !lambda return data;
-          - uart_mock.inject_rx:
-              id: virtual_uart_server_2
-              data: !lambda return data;
-
-modbus:
-  - uart_id: virtual_uart_server
-    id: virtual_modbus_server
-    role: server
-  - uart_id: virtual_uart_server_2
-    id: virtual_modbus_server_2
-    role: server
-  - uart_id: virtual_uart_controller
-    id: virtual_modbus_client
-    role: client
-    turnaround_time: 10ms
-
-modbus_controller:
-  - address: 1
-    modbus_id: virtual_modbus_client
-    update_interval: 1s
-    id: modbus_controller_1
-  - address: 2
-    modbus_id: virtual_modbus_client
-    update_interval: 1s
-    id: modbus_controller_2
-
-modbus_server:
-  - address: 1
-    modbus_id: virtual_modbus_server
-    registers:
-      - address: 0x01
-        value_type: U_WORD
-        read_lambda: return 919;
-  - address: 2
-    modbus_id: virtual_modbus_server_2
-    registers:
-      - address: 0x01
-        value_type: U_WORD
-        read_lambda: return 929;
-
-sensor:
-  - platform: modbus_controller
-    modbus_controller_id: modbus_controller_1
-    name: "reg_u_word"
-    address: 0x01
-    register_type: holding
-    value_type: U_WORD
-  - platform: modbus_controller
-    modbus_controller_id: modbus_controller_2
-    name: "reg_u_word_2"
-    address: 0x01
-    register_type: holding
-    value_type: U_WORD
-
-button:
-  - platform: template
-    name: "Start Scenario"
-    id: start_scenario_btn
-    # This test does not have anything to start (mock is autostart)

tests/integration/fixtures/uart_mock_modbus_server_injected.yaml

@@ -1,5 +1,5 @@
 esphome:
-  name: uart-mock-modbus-srv-rw
+  name: uart-mock-modbus-srv-injected
 
 host:
 api:
@@ -17,6 +17,8 @@ uart:
   baud_rate: 115200
   port: /dev/null
 
+# Shared server-role fixture (see the shared_yaml markers in the test file);
+# the injections concatenate and each test waits only on its own sensors.
 uart_mock:
   - id: virtual_uart_dev
     baud_rate: 9600
@@ -25,18 +27,31 @@ uart_mock:
     auto_start: false
     debug:
     injections:
-      # FC 0x17 Read/Write Multiple Registers on device 1:
-      #   write reg 0x0001 = 0x1234 (qty 1), then read regs 0x0001..0x0002 (qty 2).
-      # Per Modbus 6.17 the write is performed before the read, so reg 0x0001 must
-      # read back the just-written 0x1234 in the same request.
+      - delay: 100ms
+        inject_rx: [0x01, 0x03, 0x00, 0x03, 0x00, 0x01, 0x74, 0x0A] #  Read holding register 3 on device 1 (basic_read)
+      - delay: 100ms
+        #  Read holding register 7 on device 2, its reply, then read holding
+        #  register 5 on device 1 (read_after_peer_response)
+        inject_rx: [0x02, 0x03, 0x00, 0x07, 0x00, 0x01, 0x35, 0xF8,
+                    0x02, 0x03, 0x02, 0x00, 0xF0, 0xFC,
+                    0x00, 0x01, 0x03, 0x00, 0x05, 0x00, 0x01, 0x94, 0x0B]
+      - delay: 100ms
+        inject_rx: [0x02, 0x03, 0x00, 0x07, 0x00, 0x01, 0x35, 0xF8] #  Read holding register 7 on device 2, with no response
+      - delay: 100ms
+        #  Read holding register 7 on device 2 with no response, then read
+        #  holding register A on device 1 (read_after_peer_timeout)
+        inject_rx: [0x02, 0x03, 0x00, 0x07, 0x00, 0x01, 0x35, 0xF8,
+                    0x01, 0x03, 0x00, 0x0A, 0x00, 0x01, 0xA4, 0x08]
+      # FC 0x17 on device 1: write reg 0x0001 = 0x1234 then read 0x0001..0x0002;
+      # per Modbus 6.17 the write runs first, so 0x0001 must read back 0x1234.
       - delay: 100ms
         inject_rx:
           [0x01, 0x17, 0x00, 0x01, 0x00, 0x02, 0x00, 0x01, 0x00, 0x01, 0x02, 0x12, 0x34, 0x49, 0xD8]
-      # FC 0x17: write reg 0x0003 = 0x5678 (qty 1), then read reg 0x0003 (qty 1) -
+      # FC 0x17: write reg 0x0006 = 0x5678 (qty 1), then read reg 0x0006 (qty 1) -
       # a write and read targeting a different register block.
       - delay: 100ms
         inject_rx:
-          [0x01, 0x17, 0x00, 0x03, 0x00, 0x01, 0x00, 0x03, 0x00, 0x01, 0x02, 0x56, 0x78, 0x9B, 0x10]
+          [0x01, 0x17, 0x00, 0x06, 0x00, 0x01, 0x00, 0x06, 0x00, 0x01, 0x02, 0x56, 0x78, 0x8B, 0x55]
 
 globals:
   - id: stored_1
@@ -70,8 +85,18 @@ modbus_server:
         read_lambda: |-
           id(rw_read_2).publish_state(0x00AA);
           return 0x00AA;
-      # Second writable + readable register, targeted by the second request.
       - address: 0x03
+        value_type: U_WORD
+        read_lambda: |-
+          id(basic_read).publish_state(1);
+          return 1;
+      - address: 0x05
+        value_type: U_WORD
+        read_lambda: |-
+          id(read_after_peer_response).publish_state(1);
+          return 1;
+      # Second writable + readable register, targeted by the second FC 0x17 request.
+      - address: 0x06
         value_type: U_WORD
         read_lambda: |-
           id(rw_read_3).publish_state(id(stored_3));
@@ -80,8 +105,22 @@ modbus_server:
           id(stored_3) = x;
           id(rw_write_3).publish_state(x);
           return true;
+      - address: 0x0A
+        value_type: U_WORD
+        read_lambda: |-
+          id(read_after_peer_timeout).publish_state(1);
+          return 1;
 
 sensor:
+  - platform: template
+    name: "basic_read"
+    id: basic_read
+  - platform: template
+    name: "read_after_peer_response"
+    id: read_after_peer_response
+  - platform: template
+    name: "read_after_peer_timeout"
+    id: read_after_peer_timeout
   - platform: template
     name: "rw_write_1"
     id: rw_write_1

tests/integration/host_prefs.py

@@ -1,7 +1,7 @@
 """Helpers for manipulating the host platform's preferences file.
 
 ESPHome's host platform stores preferences in
-``~/.esphome/prefs/<app_name>.prefs`` using a simple binary layout that
+``$ESPHOME_PREFDIR/<app_name>.prefs`` using a simple binary layout that
 mirrors ``HostPreferences::sync()``:
 ``[uint32_t key][uint8_t len][uint8_t data[len]]`` per entry.
 
@@ -11,13 +11,21 @@ boot (e.g. forcing safe mode) or to clear stale state between runs.
 
 from __future__ import annotations
 
+import os
 from pathlib import Path
 import struct
 
 
 def host_prefs_path(device_name: str) -> Path:
-    """Return the on-disk prefs file path for a host-platform device."""
-    return Path.home() / ".esphome" / "prefs" / f"{device_name}.prefs"
+    """Return the on-disk prefs file path for a host-platform device.
+
+    Requires ESPHOME_PREFDIR, which the autouse isolated_preferences fixture
+    sets; refusing the ~/.esphome/prefs fallback keeps tests off real user
+    data if the fixture is ever bypassed."""
+    prefdir = os.environ.get("ESPHOME_PREFDIR")
+    if not prefdir:
+        raise RuntimeError("ESPHOME_PREFDIR is not set; refusing the real prefs dir")
+    return Path(prefdir) / f"{device_name}.prefs"
 
 
 def clear_host_prefs(device_name: str) -> None:

tests/integration/integration_test_durations.json

@@ -1,143 +1,154 @@
 {
-  "tests/integration/test_action_concurrent_reentry.py": 57.91,
-  "tests/integration/test_addressable_light_transition.py": 21.25,
-  "tests/integration/test_alarm_control_panel_state_transitions.py": 70.71,
-  "tests/integration/test_api_action_metadata.py": 66.6,
-  "tests/integration/test_api_action_responses.py": 36.1,
-  "tests/integration/test_api_action_timeout.py": 68.86,
-  "tests/integration/test_api_conditional_memory.py": 15.48,
-  "tests/integration/test_api_custom_services.py": 18.77,
-  "tests/integration/test_api_get_time_response_timezone.py": 21.08,
-  "tests/integration/test_api_homeassistant.py": 65.59,
-  "tests/integration/test_api_homeassistant_action_no_subscriber.py": 18.44,
-  "tests/integration/test_api_homeassistant_binary_sensor_initial_state.py": 15.05,
-  "tests/integration/test_api_list_entities_backpressure.py": 13.88,
-  "tests/integration/test_api_message_size_batching.py": 29.98,
-  "tests/integration/test_api_reboot_timeout.py": 16.05,
-  "tests/integration/test_api_string_lambda.py": 15.31,
-  "tests/integration/test_api_vv_logging.py": 19.28,
-  "tests/integration/test_api_zero_psk_provisioning.py": 31.5,
-  "tests/integration/test_areas_and_devices.py": 24.95,
-  "tests/integration/test_automation_wait_actions.py": 20.92,
-  "tests/integration/test_automations.py": 35.19,
-  "tests/integration/test_batch_delay_zero_rapid_transitions.py": 17.99,
-  "tests/integration/test_binary_sensor_autorepeat_filter.py": 20.39,
-  "tests/integration/test_binary_sensor_invalidate_state.py": 18.41,
-  "tests/integration/test_blocking_warning_log_time_not_charged_to_next_operation.py": 24.69,
-  "tests/integration/test_build_info.py": 18.7,
-  "tests/integration/test_camera_mock.py": 16.23,
-  "tests/integration/test_climate_control_action.py": 21.14,
-  "tests/integration/test_climate_custom_modes.py": 20.74,
-  "tests/integration/test_continuation_actions.py": 16.81,
-  "tests/integration/test_cover_control_action.py": 20.34,
-  "tests/integration/test_crc8_helper.py": 9.36,
-  "tests/integration/test_device_id_in_state.py": 44.67,
-  "tests/integration/test_duplicate_entities.py": 23.58,
-  "tests/integration/test_entity_icon.py": 34.35,
-  "tests/integration/test_fan_turn_on_action.py": 24.23,
-  "tests/integration/test_fnv1_hash_object_id.py": 16.21,
-  "tests/integration/test_fnv1a_hash.py": 13.38,
-  "tests/integration/test_gpio_expander_cache.py": 13.06,
-  "tests/integration/test_host_logger_thread_safety.py": 23.66,
-  "tests/integration/test_host_mode_basic.py": 8.01,
-  "tests/integration/test_host_mode_batch_delay.py": 21.0,
-  "tests/integration/test_host_mode_climate_basic_state.py": 22.14,
-  "tests/integration/test_host_mode_climate_control.py": 19.39,
-  "tests/integration/test_host_mode_empty_string_options.py": 21.76,
-  "tests/integration/test_host_mode_entity_fields.py": 29.61,
-  "tests/integration/test_host_mode_fan_preset.py": 20.01,
-  "tests/integration/test_host_mode_many_entities.py": 39.08,
-  "tests/integration/test_host_mode_many_entities_multiple_connections.py": 23.92,
-  "tests/integration/test_host_mode_noise_encryption.py": 42.42,
-  "tests/integration/test_host_mode_reconnect.py": 3.41,
-  "tests/integration/test_host_mode_sensor.py": 22.96,
-  "tests/integration/test_host_ota.py": 29.5,
-  "tests/integration/test_host_preferences.py": 16.06,
-  "tests/integration/test_host_preferences_suspend_resume.py": 18.71,
-  "tests/integration/test_improv_serial_uart.py": 20.22,
-  "tests/integration/test_large_message_batching.py": 26.56,
-  "tests/integration/test_legacy_area.py": 22.72,
-  "tests/integration/test_legacy_climate_compat.py": 14.13,
-  "tests/integration/test_legacy_fan_compat.py": 14.33,
-  "tests/integration/test_light_automations.py": 18.81,
-  "tests/integration/test_light_binary_effect_off_phase.py": 8.38,
-  "tests/integration/test_light_calls.py": 21.88,
-  "tests/integration/test_light_constant_brightness.py": 59.45,
-  "tests/integration/test_light_control_action.py": 31.91,
-  "tests/integration/test_light_dim_relative_action.py": 14.43,
-  "tests/integration/test_light_effect_zero_brightness.py": 25.05,
-  "tests/integration/test_light_initial_state.py": 18.97,
-  "tests/integration/test_light_toggle_action.py": 17.44,
-  "tests/integration/test_lock_automations.py": 18.9,
-  "tests/integration/test_logger_buffered_recursion_guard.py": 18.2,
-  "tests/integration/test_loop_disable_enable.py": 63.35,
-  "tests/integration/test_loop_interval_decoupling.py": 17.7,
-  "tests/integration/test_loop_interval_default_not_pulled_forward.py": 21.56,
-  "tests/integration/test_micros_to_millis.py": 15.89,
-  "tests/integration/test_multi_click_trigger.py": 17.23,
-  "tests/integration/test_multi_device_preferences.py": 19.4,
-  "tests/integration/test_noise_encryption_key_protection.py": 72.59,
-  "tests/integration/test_object_id_api_verification.py": 19.22,
-  "tests/integration/test_object_id_friendly_name_no_mac_suffix.py": 16.77,
-  "tests/integration/test_object_id_no_friendly_name.py": 45.8,
-  "tests/integration/test_online_image_auto_detects_image_bmp_mime.py": 86.73,
-  "tests/integration/test_online_image_auto_detects_redirected_image_bmp_mime.py": 40.4,
-  "tests/integration/test_online_image_bmp.py": 37.24,
-  "tests/integration/test_oversized_payloads.py": 55.75,
-  "tests/integration/test_preference_key_stability.py": 25.49,
-  "tests/integration/test_runtime_stats.py": 29.81,
-  "tests/integration/test_safe_mode_loop_runs.py": 6.26,
-  "tests/integration/test_scheduler_blocking_warning.py": 37.98,
-  "tests/integration/test_scheduler_bulk_cleanup.py": 18.67,
-  "tests/integration/test_scheduler_defer_cancel.py": 18.46,
-  "tests/integration/test_scheduler_defer_cancel_regular.py": 16.34,
-  "tests/integration/test_scheduler_defer_fifo_simple.py": 18.26,
-  "tests/integration/test_scheduler_defer_stress.py": 17.74,
-  "tests/integration/test_scheduler_heap_stress.py": 3.89,
-  "tests/integration/test_scheduler_internal_id_no_collision.py": 20.01,
-  "tests/integration/test_scheduler_interval_reschedule.py": 16.29,
-  "tests/integration/test_scheduler_interval_zero_coerced.py": 16.09,
-  "tests/integration/test_scheduler_null_name.py": 14.69,
-  "tests/integration/test_scheduler_numeric_id_test.py": 17.08,
-  "tests/integration/test_scheduler_pool.py": 19.88,
-  "tests/integration/test_scheduler_rapid_cancellation.py": 4.42,
-  "tests/integration/test_scheduler_recursive_timeout.py": 4.3,
-  "tests/integration/test_scheduler_removed_item_race.py": 15.49,
-  "tests/integration/test_scheduler_self_keyed.py": 25.77,
-  "tests/integration/test_scheduler_simultaneous_callbacks.py": 14.84,
-  "tests/integration/test_scheduler_string_test.py": 15.42,
-  "tests/integration/test_script_array_params.py": 12.73,
-  "tests/integration/test_script_delay_params.py": 12.69,
-  "tests/integration/test_script_queued.py": 20.38,
-  "tests/integration/test_script_queued_idle_loop.py": 25.06,
-  "tests/integration/test_script_wait_on_boot.py": 15.67,
-  "tests/integration/test_select_stringref_trigger.py": 19.48,
-  "tests/integration/test_sensor_filters_delta.py": 27.62,
-  "tests/integration/test_sensor_filters_ring_buffer.py": 20.27,
-  "tests/integration/test_sensor_filters_sliding_window.py": 56.28,
-  "tests/integration/test_sensor_filters_value_list.py": 20.6,
-  "tests/integration/test_sensor_timeout_filter.py": 22.21,
-  "tests/integration/test_socket_wake_gate_tcp.py": 16.37,
-  "tests/integration/test_status_flags.py": 29.68,
-  "tests/integration/test_strftime_to.py": 17.42,
-  "tests/integration/test_syslog.py": 18.39,
-  "tests/integration/test_template_alarm_control_panel_many_sensors.py": 25.61,
-  "tests/integration/test_template_text_save.py": 19.16,
-  "tests/integration/test_text_command.py": 16.43,
-  "tests/integration/test_text_sensor_raw_state.py": 17.19,
-  "tests/integration/test_uart_mock_ld2410.py": 37.0,
-  "tests/integration/test_uart_mock_ld2412.py": 40.82,
-  "tests/integration/test_uart_mock_ld2420.py": 32.7,
-  "tests/integration/test_uart_mock_ld2450.py": 32.84,
-  "tests/integration/test_uart_mock_modbus.py": 548.87,
-  "tests/integration/test_udp.py": 16.67,
-  "tests/integration/test_use_address_runtime.py": 27.26,
-  "tests/integration/test_valve_control_action.py": 24.58,
-  "tests/integration/test_varint_five_byte_device_id.py": 22.5,
-  "tests/integration/test_wait_until_mid_loop_timing.py": 22.05,
-  "tests/integration/test_wait_until_on_boot.py": 10.37,
-  "tests/integration/test_wait_until_ordering.py": 18.23,
-  "tests/integration/test_wait_until_reentrant_restart.py": 19.35,
-  "tests/integration/test_wake_loop_forces_phase_b.py": 17.83,
-  "tests/integration/test_water_heater_template.py": 25.7
+  "tests/integration/test_action_concurrent_reentry.py": 30.48,
+  "tests/integration/test_addressable_light_transition.py": 42.1,
+  "tests/integration/test_alarm_control_panel_state_transitions.py": 35.76,
+  "tests/integration/test_api_action_metadata.py": 22.35,
+  "tests/integration/test_api_action_responses.py": 30.31,
+  "tests/integration/test_api_action_timeout.py": 34.73,
+  "tests/integration/test_api_conditional_memory.py": 18.35,
+  "tests/integration/test_api_custom_services.py": 15.99,
+  "tests/integration/test_api_get_time_response_timezone.py": 24.21,
+  "tests/integration/test_api_homeassistant.py": 33.77,
+  "tests/integration/test_api_homeassistant_action_no_subscriber.py": 20.8,
+  "tests/integration/test_api_homeassistant_binary_sensor_initial_state.py": 23.55,
+  "tests/integration/test_api_list_entities_backpressure.py": 23.04,
+  "tests/integration/test_api_message_size_batching.py": 27.31,
+  "tests/integration/test_api_reboot_timeout.py": 29.32,
+  "tests/integration/test_api_string_lambda.py": 14.9,
+  "tests/integration/test_api_vv_logging.py": 26.25,
+  "tests/integration/test_api_zero_psk_provisioning.py": 38.19,
+  "tests/integration/test_areas_and_devices.py": 27.52,
+  "tests/integration/test_automation_wait_actions.py": 24.25,
+  "tests/integration/test_automations.py": 36.02,
+  "tests/integration/test_batch_delay_zero_rapid_transitions.py": 18.46,
+  "tests/integration/test_binary_sensor_autorepeat_filter.py": 17.47,
+  "tests/integration/test_binary_sensor_invalidate_state.py": 14.79,
+  "tests/integration/test_blocking_warning_log_time_not_charged_to_next_operation.py": 21.52,
+  "tests/integration/test_build_info.py": 21.42,
+  "tests/integration/test_camera_mock.py": 17.02,
+  "tests/integration/test_climate_control_action.py": 26.56,
+  "tests/integration/test_climate_custom_modes.py": 18.82,
+  "tests/integration/test_continuation_actions.py": 20.39,
+  "tests/integration/test_cover_control_action.py": 19.91,
+  "tests/integration/test_crc8_helper.py": 16.73,
+  "tests/integration/test_device_id_in_state.py": 58.41,
+  "tests/integration/test_duplicate_entities.py": 30.76,
+  "tests/integration/test_entity_icon.py": 25.34,
+  "tests/integration/test_fan_turn_on_action.py": 23.64,
+  "tests/integration/test_fnv1_hash_object_id.py": 25.44,
+  "tests/integration/test_fnv1a_hash.py": 20.85,
+  "tests/integration/test_gpio_expander_cache.py": 14.42,
+  "tests/integration/test_host_logger_thread_safety.py": 21.31,
+  "tests/integration/test_host_mode_basic.py": 2.65,
+  "tests/integration/test_host_mode_batch_delay.py": 22.21,
+  "tests/integration/test_host_mode_climate_basic_state.py": 27.12,
+  "tests/integration/test_host_mode_climate_control.py": 21.57,
+  "tests/integration/test_host_mode_empty_string_options.py": 27.17,
+  "tests/integration/test_host_mode_entity_fields.py": 30.1,
+  "tests/integration/test_host_mode_fan_preset.py": 17.55,
+  "tests/integration/test_host_mode_many_entities.py": 38.98,
+  "tests/integration/test_host_mode_many_entities_multiple_connections.py": 23.82,
+  "tests/integration/test_host_mode_noise_encryption.py": 39.84,
+  "tests/integration/test_host_mode_reconnect.py": 13.1,
+  "tests/integration/test_host_mode_sensor.py": 22.17,
+  "tests/integration/test_host_ota.py": 92.05,
+  "tests/integration/test_host_preferences.py": 20.29,
+  "tests/integration/test_host_preferences_suspend_resume.py": 15.02,
+  "tests/integration/test_improv_serial_uart.py": 30.15,
+  "tests/integration/test_large_message_batching.py": 25.84,
+  "tests/integration/test_legacy_area.py": 21.24,
+  "tests/integration/test_legacy_climate_compat.py": 17.34,
+  "tests/integration/test_legacy_fan_compat.py": 22.6,
+  "tests/integration/test_light_automations.py": 29.13,
+  "tests/integration/test_light_binary_effect_off_phase.py": 33.99,
+  "tests/integration/test_light_calls.py": 26.81,
+  "tests/integration/test_light_constant_brightness.py": 25.0,
+  "tests/integration/test_light_control_action.py": 25.57,
+  "tests/integration/test_light_dim_relative_action.py": 21.4,
+  "tests/integration/test_light_effect_zero_brightness.py": 19.65,
+  "tests/integration/test_light_initial_state.py": 17.58,
+  "tests/integration/test_light_toggle_action.py": 28.28,
+  "tests/integration/test_lock_automations.py": 23.3,
+  "tests/integration/test_logger_buffered_recursion_guard.py": 22.96,
+  "tests/integration/test_loop_disable_enable.py": 16.18,
+  "tests/integration/test_loop_interval_decoupling.py": 25.19,
+  "tests/integration/test_loop_interval_default_not_pulled_forward.py": 20.59,
+  "tests/integration/test_lvgl_headless_render.py": 87.78,
+  "tests/integration/test_micros_to_millis.py": 18.73,
+  "tests/integration/test_multi_click_trigger.py": 24.2,
+  "tests/integration/test_multi_device_preferences.py": 20.52,
+  "tests/integration/test_noise_encryption_key_protection.py": 19.1,
+  "tests/integration/test_object_id_api_verification.py": 26.24,
+  "tests/integration/test_object_id_friendly_name_no_mac_suffix.py": 14.88,
+  "tests/integration/test_object_id_no_friendly_name.py": 61.27,
+  "tests/integration/test_online_image_auto_detects_image_bmp_mime.py": 82.32,
+  "tests/integration/test_online_image_auto_detects_redirected_image_bmp_mime.py": 46.03,
+  "tests/integration/test_online_image_bmp.py": 34.21,
+  "tests/integration/test_oversized_payloads.py": 62.75,
+  "tests/integration/test_preference_key_stability.py": 26.8,
+  "tests/integration/test_runtime_stats.py": 28.26,
+  "tests/integration/test_safe_mode_loop_runs.py": 18.14,
+  "tests/integration/test_scheduler_blocking_warning.py": 28.7,
+  "tests/integration/test_scheduler_bulk_cleanup.py": 20.73,
+  "tests/integration/test_scheduler_defer_cancel.py": 22.99,
+  "tests/integration/test_scheduler_defer_cancel_regular.py": 21.97,
+  "tests/integration/test_scheduler_defer_fifo_simple.py": 24.15,
+  "tests/integration/test_scheduler_defer_stress.py": 23.11,
+  "tests/integration/test_scheduler_heap_stress.py": 20.2,
+  "tests/integration/test_scheduler_internal_id_no_collision.py": 23.75,
+  "tests/integration/test_scheduler_interval_reschedule.py": 15.32,
+  "tests/integration/test_scheduler_interval_zero_coerced.py": 20.1,
+  "tests/integration/test_scheduler_null_name.py": 17.43,
+  "tests/integration/test_scheduler_numeric_id_test.py": 25.51,
+  "tests/integration/test_scheduler_pool.py": 24.22,
+  "tests/integration/test_scheduler_rapid_cancellation.py": 24.01,
+  "tests/integration/test_scheduler_recursive_timeout.py": 22.94,
+  "tests/integration/test_scheduler_removed_item_race.py": 23.07,
+  "tests/integration/test_scheduler_self_keyed.py": 18.43,
+  "tests/integration/test_scheduler_simultaneous_callbacks.py": 21.99,
+  "tests/integration/test_scheduler_string_test.py": 17.27,
+  "tests/integration/test_script_array_params.py": 4.59,
+  "tests/integration/test_script_delay_params.py": 22.46,
+  "tests/integration/test_script_queued.py": 25.24,
+  "tests/integration/test_script_queued_idle_loop.py": 5.04,
+  "tests/integration/test_script_wait_on_boot.py": 21.77,
+  "tests/integration/test_sdl_headless_screenshot.py": 19.23,
+  "tests/integration/test_select_stringref_trigger.py": 19.31,
+  "tests/integration/test_sensor_filters_delta.py": 25.92,
+  "tests/integration/test_sensor_filters_ring_buffer.py": 22.39,
+  "tests/integration/test_sensor_filters_sliding_window.py": 57.93,
+  "tests/integration/test_sensor_filters_value_list.py": 20.32,
+  "tests/integration/test_sensor_timeout_filter.py": 25.35,
+  "tests/integration/test_snapshot_display.py": 19.7,
+  "tests/integration/test_socket_wake_gate_tcp.py": 14.5,
+  "tests/integration/test_status_flags.py": 33.83,
+  "tests/integration/test_strftime_to.py": 17.64,
+  "tests/integration/test_syslog.py": 24.49,
+  "tests/integration/test_template_alarm_control_panel_many_sensors.py": 24.81,
+  "tests/integration/test_template_climate_basic.py": 15.28,
+  "tests/integration/test_template_climate_custom_modes.py": 25.07,
+  "tests/integration/test_template_climate_nonoptimistic.py": 24.25,
+  "tests/integration/test_template_climate_on_control_ordering.py": 24.09,
+  "tests/integration/test_template_climate_publish_all_fields.py": 17.78,
+  "tests/integration/test_template_climate_sensor_push.py": 17.42,
+  "tests/integration/test_template_climate_set_actions.py": 23.63,
+  "tests/integration/test_template_climate_two_point_temperature.py": 25.19,
+  "tests/integration/test_template_text_save.py": 17.88,
+  "tests/integration/test_text_command.py": 22.71,
+  "tests/integration/test_text_sensor_raw_state.py": 25.17,
+  "tests/integration/test_uart_mock_ld2410.py": 58.15,
+  "tests/integration/test_uart_mock_ld2412.py": 61.14,
+  "tests/integration/test_uart_mock_ld2420.py": 33.87,
+  "tests/integration/test_uart_mock_ld2450.py": 26.06,
+  "tests/integration/test_uart_mock_modbus.py": 391.79,
+  "tests/integration/test_udp.py": 7.38,
+  "tests/integration/test_use_address_runtime.py": 24.09,
+  "tests/integration/test_valve_control_action.py": 23.22,
+  "tests/integration/test_varint_five_byte_device_id.py": 17.93,
+  "tests/integration/test_wait_until_mid_loop_timing.py": 22.26,
+  "tests/integration/test_wait_until_on_boot.py": 17.46,
+  "tests/integration/test_wait_until_ordering.py": 11.89,
+  "tests/integration/test_wait_until_reentrant_restart.py": 22.88,
+  "tests/integration/test_wake_loop_forces_phase_b.py": 16.6,
+  "tests/integration/test_water_heater_template.py": 19.66
 }

tests/integration/raw_api_client.py

@@ -125,11 +125,12 @@ class RawApiClient:
         await self.read_until_frame(MESSAGE_TYPE_OF[api_pb2.HelloResponse])
 
     async def send_message(self, msg: message.Message) -> None:
+        await self.send_raw(MESSAGE_TYPE_OF[type(msg)], msg.SerializeToString())
+
+    async def send_raw(self, msg_type: int, payload: bytes) -> None:
+        """Send a frame with a hand built payload, for shapes protobuf will not serialize."""
         loop = asyncio.get_running_loop()
-        await loop.sock_sendall(
-            self._sock,
-            encode_frame(MESSAGE_TYPE_OF[type(msg)], msg.SerializeToString()),
-        )
+        await loop.sock_sendall(self._sock, encode_frame(msg_type, payload))
 
     async def read_until_frame(self, msg_type: int, timeout: float = 10.0) -> None:
         """Read until at least one frame of msg_type has been received."""

tests/integration/state_utils.py

@@ -57,6 +57,46 @@ async def wait_for_state(
     return await asyncio.wait_for(future, timeout=timeout)
 
 
+class StateWaiter:
+    """Route one state subscription to any number of predicate waits."""
+
+    def __init__(self) -> None:
+        self._waiters: list[
+            tuple[Callable[[EntityState], bool], asyncio.Future[EntityState]]
+        ] = []
+
+    def on_state(self, state: EntityState) -> None:
+        for predicate, future in self._waiters:
+            if future.done():
+                continue
+            try:
+                matched = predicate(state)
+            except Exception as exc:  # noqa: BLE001  the wait re-raises it, the callback must not die
+                future.set_exception(exc)
+                continue
+            if matched:
+                future.set_result(state)
+
+    async def expect(
+        self,
+        predicate: Callable[[EntityState], bool],
+        timeout: float = 5.0,
+        label: str | None = None,
+    ) -> EntityState:
+        """Wait for the next state matching ``predicate``; states seen before this call do not count."""
+        entry = (predicate, asyncio.get_running_loop().create_future())
+        self._waiters.append(entry)
+        try:
+            async with asyncio.timeout(timeout):
+                return await entry[1]
+        except TimeoutError:
+            raise TimeoutError(
+                f"no state matched {label or predicate} within {timeout}s"
+            ) from None
+        finally:
+            self._waiters.remove(entry)
+
+
 def find_entity[T: EntityInfo](
     entities: list[EntityInfo],
     object_id_substring: str,