From 1307faef06d60941f65d4cbcfec46e5dbd9981ed Mon Sep 17 00:00:00 2001
From: "J. Nick Koston" <nick@koston.org>
Date: Sat, 17 Oct 2026 16:31:17 -1000
Subject: [PATCH] [core] Add Component::status_comm_result (#20863)

---
 esphome/core/component.cpp                    |  9 ++++++
 esphome/core/component.h                      |  5 ++++
 .../core/test_status_comm_result.cpp          | 30 +++++++++++++++++++
 3 files changed, 44 insertions(+)
 create mode 100644 tests/components/core/test_status_comm_result.cpp

diff --git a/esphome/core/component.cpp b/esphome/core/component.cpp
index edcd922aebd..f65ec469ef0 100644
--- a/esphome/core/component.cpp
+++ b/esphome/core/component.cpp
@@ -290,6 +290,15 @@ void Component::status_set_warning(const LogString *message) {
   ESP_LOGW(TAG, "%s set Warning flag: %s", LOG_STR_ARG(this->get_component_log_str()),
            message ? LOG_STR_ARG(message) : LOG_STR_LITERAL("unspecified"));
 }
+bool Component::status_comm_result(bool ok) { return this->status_comm_result(ok, LOG_STR(ESP_LOG_MSG_COMM_FAIL)); }
+bool Component::status_comm_result(bool ok, const LogString *message) {
+  if (ok) {
+    this->status_clear_warning();
+  } else {
+    this->status_set_warning(message);
+  }
+  return ok;
+}
 void Component::status_set_error() { this->status_set_error((const LogString *) nullptr); }
 void Component::status_set_error(const LogString *message) {
   if (this->set_error_flag_(message) && message != nullptr) {
diff --git a/esphome/core/component.h b/esphome/core/component.h
index 0e95f8d4e90..df51af65df5 100644
--- a/esphome/core/component.h
+++ b/esphome/core/component.h
@@ -285,6 +285,11 @@ class Component {
   void status_set_warning(const char *message);
   void status_set_warning(const LogString *message);
 
+  /// Clears the warning when `ok`, else sets it with `message` (default "Communication failed"); returns `ok`.
+  /// Replaces the `if (!read()) { status_set_warning(...); return; } status_clear_warning();` pattern.
+  bool status_comm_result(bool ok);
+  bool status_comm_result(bool ok, const LogString *message);
+
   void status_set_error();  // Set error flag without message
   void status_set_error(const LogString *message);
 
diff --git a/tests/components/core/test_status_comm_result.cpp b/tests/components/core/test_status_comm_result.cpp
new file mode 100644
index 00000000000..125b43a1b8a
--- /dev/null
+++ b/tests/components/core/test_status_comm_result.cpp
@@ -0,0 +1,30 @@
+#include <gtest/gtest.h>
+
+#include "esphome/core/component.h"
+#include "esphome/core/log.h"
+
+namespace esphome {
+
+TEST(StatusCommResult, FailureSetsWarningAndSuccessClearsIt) {
+  Component component;
+  EXPECT_FALSE(component.status_comm_result(false));
+  EXPECT_TRUE(component.status_has_warning());
+  EXPECT_TRUE(component.status_comm_result(true));
+  EXPECT_FALSE(component.status_has_warning());
+}
+
+TEST(StatusCommResult, CustomMessageOverload) {
+  Component component;
+  EXPECT_FALSE(component.status_comm_result(false, LOG_STR("Bad CRC")));
+  EXPECT_TRUE(component.status_has_warning());
+  EXPECT_TRUE(component.status_comm_result(true, LOG_STR("Bad CRC")));
+  EXPECT_FALSE(component.status_has_warning());
+}
+
+TEST(StatusCommResult, SuccessWithoutWarningStaysClear) {
+  Component component;
+  EXPECT_TRUE(component.status_comm_result(true));
+  EXPECT_FALSE(component.status_has_warning());
+}
+
+}  // namespace esphome