From 80265a6bd2ad9208b3fa0b0ee8137495b4aeb7f0 Mon Sep 17 00:00:00 2001
From: Petr Kejval <petr.kejval6@gmail.com>
Date: Tue, 21 Oct 2025 15:17:07 +0200
Subject: [PATCH] [sensor] Add optimistic option to heartbeat filter (#10993)

Co-authored-by: Jonathan Swoboda <154711427+swoboda1337@users.noreply.github.com>
Co-authored-by: J. Nick Koston <nick@koston.org>
---
 esphome/components/sensor/__init__.py      | 23 +++++++++++++++++++++-
 esphome/components/sensor/filter.cpp       |  5 +++++
 esphome/components/sensor/filter.h         |  5 +++--
 tests/components/template/common-base.yaml |  3 +++
 4 files changed, 33 insertions(+), 3 deletions(-)

diff --git a/esphome/components/sensor/__init__.py b/esphome/components/sensor/__init__.py
index e603896f6d..7e91bb83c4 100644
--- a/esphome/components/sensor/__init__.py
+++ b/esphome/components/sensor/__init__.py
@@ -28,6 +28,8 @@ from esphome.const import (
     CONF_ON_RAW_VALUE,
     CONF_ON_VALUE,
     CONF_ON_VALUE_RANGE,
+    CONF_OPTIMISTIC,
+    CONF_PERIOD,
     CONF_QUANTILE,
     CONF_SEND_EVERY,
     CONF_SEND_FIRST_AT,
@@ -644,10 +646,29 @@ async def throttle_with_priority_filter_to_code(config, filter_id):
     return cg.new_Pvariable(filter_id, config[CONF_TIMEOUT], template_)
 
 
+HEARTBEAT_SCHEMA = cv.Schema(
+    {
+        cv.Required(CONF_PERIOD): cv.positive_time_period_milliseconds,
+        cv.Optional(CONF_OPTIMISTIC, default=False): cv.boolean,
+    }
+)
+
+
 @FILTER_REGISTRY.register(
-    "heartbeat", HeartbeatFilter, cv.positive_time_period_milliseconds
+    "heartbeat",
+    HeartbeatFilter,
+    cv.Any(
+        cv.positive_time_period_milliseconds,
+        HEARTBEAT_SCHEMA,
+    ),
 )
 async def heartbeat_filter_to_code(config, filter_id):
+    if isinstance(config, dict):
+        var = cg.new_Pvariable(filter_id, config[CONF_PERIOD])
+        await cg.register_component(var, {})
+        cg.add(var.set_optimistic(config[CONF_OPTIMISTIC]))
+        return var
+
     var = cg.new_Pvariable(filter_id, config)
     await cg.register_component(var, {})
     return var
diff --git a/esphome/components/sensor/filter.cpp b/esphome/components/sensor/filter.cpp
index e8d04d161b..65d8dea31c 100644
--- a/esphome/components/sensor/filter.cpp
+++ b/esphome/components/sensor/filter.cpp
@@ -372,8 +372,12 @@ optional<float> HeartbeatFilter::new_value(float value) {
   this->last_input_ = value;
   this->has_value_ = true;
 
+  if (this->optimistic_) {
+    return value;
+  }
   return {};
 }
+
 void HeartbeatFilter::setup() {
   this->set_interval("heartbeat", this->time_period_, [this]() {
     ESP_LOGVV(TAG, "HeartbeatFilter(%p)::interval(has_value=%s, last_input=%f)", this, YESNO(this->has_value_),
@@ -384,6 +388,7 @@ void HeartbeatFilter::setup() {
     this->output(this->last_input_);
   });
 }
+
 float HeartbeatFilter::get_setup_priority() const { return setup_priority::HARDWARE; }
 
 CalibrateLinearFilter::CalibrateLinearFilter(std::initializer_list<std::array<float, 3>> linear_functions)
diff --git a/esphome/components/sensor/filter.h b/esphome/components/sensor/filter.h
index 03a1e0f24c..ecd55308d1 100644
--- a/esphome/components/sensor/filter.h
+++ b/esphome/components/sensor/filter.h
@@ -396,15 +396,16 @@ class HeartbeatFilter : public Filter, public Component {
   explicit HeartbeatFilter(uint32_t time_period);
 
   void setup() override;
-
   optional<float> new_value(float value) override;
-
   float get_setup_priority() const override;
 
+  void set_optimistic(bool optimistic) { this->optimistic_ = optimistic; }
+
  protected:
   uint32_t time_period_;
   float last_input_;
   bool has_value_{false};
+  bool optimistic_{false};
 };
 
 class DeltaFilter : public Filter {
diff --git a/tests/components/template/common-base.yaml b/tests/components/template/common-base.yaml
index ea812532d4..b873af5207 100644
--- a/tests/components/template/common-base.yaml
+++ b/tests/components/template/common-base.yaml
@@ -101,6 +101,9 @@ sensor:
       - filter_out: 10
       - filter_out: !lambda return NAN;
       - heartbeat: 5s
+      - heartbeat:
+          period: 5s
+          optimistic: true
       - lambda: return x * (9.0/5.0) + 32.0;
       - max:
           window_size: 10